We can setup different environments for development work. So far, we have two choices, one is cord-in-a-box (CiaB), another is just a single VM for local development.
Choice 1: Setup CiaB based development environment.
Download and run the cord-in-a-box.sh script on the target server. The script's output is displayed and also saved to
The script takes a long time (at least two hours) to run. Be patient! If it hasn't completely failed yet, then assume all is well!
Development Workflow on CiaB
CORD-in-a-Box is a useful environment for integration testing and debugging. A typical scenario is to find a problem, and then rebuild and redeploy some XOS containers (e.g., a service synchronizer) to verify a fix. A workflow for quickly rebuilding and redeploying the XOS containers from source is:
Make changes in your source tree, under:
Login to the
corddev VM by using
First, if you made any changes to a profile (e.g., you added a new service), you'll need to re-sync the configuration from the build node to the head node. To do this run:
Then re-build and re-publish new images:
Now the new XOS images should be published to the registry on
prod. To bring them up, login to the
prod VM and define these aliases:
To pull new images from the database and launch the containers, while retaining the existing XOS database, run:
Alternatively, to remove the XOS database and reinitialize XOS from scratch, run:
Adding Tenants and Instances in TOSCA
You must onboard any tenant or instance TOSCA definitions separately from the rest of your service definitions. This is because in the build sequence above, the compute node is reprovisioned last, meaning that any instances that you define will not have any compute node to host them at the time the TOSCA is compiled. Therefore, for proper functionality/behavior, it is recommended that any TOSCA tenants or instances are defined in cord/build/platform-install/roles/test-mcord-tenants-config/templates/onboard-mcord-tenants.yaml.j2. To onboard this file, simply add and run the ansible playbook alias below from the prod VM.
Choice 2: Deploy Locally on a VM
If you are doing work that does not involve OpenStack you can create a development environment inside a VM on your local machine. This environment is mostly designed to do GUI, APIs and modeling related work. It can also be useful to test a synchronizer whose job is synchronizing data using REST APIs.
*Note - This quick start guide has only been tested against Vagrant (v1.9.5) and VirtualBox (v5.1.22), specifically on MacOS.
The following dependencies/prerequisites are required to implement this approach:
Installing the Dependencies
The latest versions of each software can be found on their support pages, however homebrew can do it for us:
If you do not have homebrew available, please download Vagrant and VirtualBox. Below are instructions on how to pull repo's source code directly. Since CORD consists of 40+ repositories and changes can easily span multiple repositories, we use the repo tool to help us manage this complexity.
Setting Up the Environment
Create a dedicated directory for the CORD source code and use repo to pull the source code from gerrit
Start & Connect to the Head-Node VM
We provide a Vagrant VM where a container housing the XOS orchestrator resides. In the Cord-in-a-Box implementation, we can also start containers for ONOS, OpenStack, and MAAS (Metal-as-a-Service), however CiaB installation can take upwards of 2 hours to complete. This guide is meant for GUI, service profiles, and API related development to avoid the unnecessary overhead of the other components. The Vagrantfile for this VM is located in the build/platform-install directory. Below are the results after running 'vagrant status':
Once the VM is up and provisioned, vagrant status will look like:
Now, we can connect to the VM
Start the XOS Container w/ M-CORD Profile
Most profiles are run by specifying an inventory file when running
ansible-playbook. For most frontend or mock profiles, you'll want to run the
deploy-xos-playbook.yml playbook. To run the M-CORD profile, run:
More information on deploying other CORD profiles can be found here: https://github.com/opencord/platform-install#development-loop.
Not in `docker` Usergroup
Your user may not be a member of the `docker` user group when you first connect to the head-node VM. This can cause a permissions error with regards to the Dockerfile inside the head-node. To be added to the user group, simply log out, and log back into the VM. You can verify your membership by running the `groups` command.
Connecting to the GUI
Deploying the M-CORD profile for the first time will take close to 20 minutes in order to set up the development environment. Once complete, you can connect to the XOS GUI running in the head-node. In the Vagrantfile, note that the VM's IP address is 192.168.46.100. You can also confirm this using 'ifconfig' in the VM.
Your host machine and the VM are connected using a VirtualBox network interface created upon the launch of the VM. This means that you can connect to the XOS GUI by pointing your host machine's browser to 192.168.46.100/xos/. The username is email@example.com, and the password is auto generated in the /firstname.lastname@example.org file. The main page for the XOS GUI will look like this after log-in.
As you can see, the M-CORD profile has clearly been launched. Also, note that the service dependency graph is empty. This is because, as explained earlier, this is meant to be a bare installation of M-CORD. Should you want to proceed to a full CiaB run-through, see choice 1 above or use this guide, https://github.com/opencord/cord/blob/cord-3.0/docs/quickstart.md.
When you are done using the VM, tear down the profile, exit the VM, and shut it down.