Pull out devel env setup to a separate .md
Change-Id: Id8f4ae0d9dd4596e41901c2a46eae172424e8a8a
diff --git a/docs/devel_env_setup.md b/docs/devel_env_setup.md
new file mode 100644
index 0000000..b8f2e18
--- /dev/null
+++ b/docs/devel_env_setup.md
@@ -0,0 +1,59 @@
+# The CORD Development Environment
+
+The development environment is required for the tasks in this repository.
+This environment leverages [Vagrant](https://www.vagrantup.com/docs/getting-started/)
+to install the tools required to build and deploy the CORD software.
+
+## Cloning the Repository
+To clone the repository, on your build host issue the `git` command:
+```
+git clone http://gerrit.opencord.org/cord
+```
+
+### Complete
+When this is complete, a listing (`ls`) of this directory should yield output
+similar to:
+```
+ls
+LICENSE.txt ansible/ components/ gradle/ gradlew.bat utils/
+README.md build.gradle config/ gradle.properties scripts/
+Vagrantfile buildSrc/ docs/ gradlew* settings.gradle
+```
+## Creating the Development Machine
+To create the development machine the following Vagrant command can be
+used. This will create an Ubuntu 14.04 LTS based virtual machine and install
+some basic required packages, such as Docker, Docker Compose, and
+Oracle Java 8.
+```
+vagrant up corddev
+```
+**NOTE:** *It may have several minutes for the first command `vagrant up
+corddev` to complete as it will include creating the VM as well as downloading
+and installing various software packages.*
+
+## Connect to the Development Machine
+To connect to the development machine the following vagrant command can be used.
+```
+vagrant ssh corddev
+```
+
+Once connected to the Vagrant machine, you can find the deployment artifacts
+in the `/cord` directory on the VM.
+```
+cd /cord
+```
+
+## Gradle
+[Gradle](https://gradle.org/) is the build tool that is used to help
+orchestrate the build and deployment of a POD. A *launch* script is included
+in the Vagrant machine that will automatically download and install `gradle`.
+The script is called `gradlew` and the download / install will be invoked on
+the first use of this script; thus the first use may take a little longer
+than subsequent invocations and requires a connection to the internet.
+
+### Complete
+Once you have created and connected to the development environment this task is
+complete. The `cord` repository files can be found on the development machine
+under `/cord`. This directory is mounted from the host machine so changes
+made to files in this directory will be reflected on the host machine and
+vice-versa.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index cbde2a3..48ebb3e 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -20,7 +20,7 @@
4. Run some tests on the platform
5. Clean-up
-### What you need (Prerequisites)
+## What you need (Prerequisites)
You will need a build machine (can be your developer laptop) and a target server.
@@ -59,48 +59,35 @@
Refer to the [CloudLab documentation](https://docs.cloudlab.us) for more information.
-### Bring up the CORD Build Environment
+## Create the development environment
-On the build host, clone the CORD integration repository anonymously and switch into its top directory:
+Follow the instructions in [devel_env_setup.md](./devel_env_setup.md) to set
+up the Vagrant development machine for CORD on your build host.
- ```
- git clone https://gerrit.opencord.org/cord
- cd cord
- ```
+The rest of the tasks in this guide are run from inside the Vagrant development
+machine, in the `/cord` directory.
-If -- for whatever reason -- you decide to clone the repo as a private
-repository using ssh, then you should add your private key to your local ssh
-forwarding agent, because we will clone additional CORD repositories within
-the Vagrant environment using the same git access mode, and this will require your
-local agent to know your identity:
+## Fetch
+The fetching phase of the deployment pulls Docker images from the public
+repository down to the local machine as well as clones any `git` submodules
+that are part of the project. This phase can be initiated with the following
+command:
+```
+./gradlew fetch
+```
- ```
- ssh-add ~/.ssh/id_rsa
- ```
-
-Bring up the standardized CORD build and development environment (VM). This will take a few minutes, depending on your connection speed:
-
- ```
- vagrant up corddev
- ```
-
-Login to the build environment:
-
- ```
- vagrant ssh corddev
- ```
-
-Switch to the CORD integration directory, which is shared from your host:
-
- ```
- cd /cord
- ```
-
-Pre-fetch all pre-requisites needed to build all components for CORD. This step can take a while as a large number of images and files need to be downloaded.
-
- ```
- ./gradlew fetch
- ```
+### Complete
+Once the fetch command has successfully been run, this step is complete. After
+this command completes you should be able to see the Docker images that were
+downloaded using the `docker images` command on the development machine:
+```
+docker images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+python 2.7-alpine 836fa7aed31d 5 days ago 56.45 MB
+consul <none> 62f109a3299c 2 weeks ago 41.05 MB
+registry 2.4.0 8b162eee2794 9 weeks ago 171.1 MB
+abh1nav/dockerui latest 6e4d05915b2a 19 months ago 469.5 MB
+```
## Edit the configuration file
@@ -108,29 +95,29 @@
server as well as the `username / password` for accessing the server. You can skip adding the password if you can SSH
to the target server from inside the Vagrant VM as `username` without one (e.g., by running `ssh-agent`).
-Before proceeding, verify that you can SSH to the target server from the development environment using the
-above IP address, username, and password. Also verify that the user account can `sudo` without a password.
+If you are planning on deploying the single-node POD to a CloudLab host, uncomment
+the following lines in the configuration file:
-Edit `/cord/gradle.properties` to add the following line:
+```
+#extraVars:
+# - 'on_cloudlab=True'
+```
- ```
- deployConfig=/cord/components/platform-install/config/default.yml
- ```
+This will signal the install process to set up extra disk space on the CloudLab
+node for use by CORD.
-If your target server is a CloudLab machine, uncomment the following two lines in the
-configuration file:
+### Complete
- ```
- #extraVars:
- # - 'on_cloudlab=True'
- ```
+Before proceeding, verify that you can SSH to the target server from the development
+environment using the IP address, username, and password that you entered into the
+configuration file. Also verify that the user account can `sudo` without a password.
-### Deploy the single-node CORD POD on the target server
+## Deploy the single-node CORD POD on the target server
Deploy the CORD software to the the target server and configure it to form a running POD.
- ```
- ./gradlew deploySingle
+```
+./gradlew -PdeployConfig=/cord/components/platform-install/config/default.yml deploySingle
```
> *What this does:*
>
@@ -140,22 +127,48 @@
Note that this step usually takes *at least an hour* to complete. Be patient!
-Execute a set of basic health tests on the platform:
+### Complete
- ```
- ./gradlew post-deploy-tests
- ```
+This step is completed once the Ansible playbook finishes without errors. If
+an error is encountered when running this step, the first thing to try is
+just running the above `gradlew` command again.
+Once the step completes, two instances of ONOS are running, in
+the `onos-cord-1` and `onos-fabric-1` VMs, though only `onos-cord-1` is used in
+the single-node install. OpenStack is also running on the target server with a virtual
+compute node called `nova-compute-1`. Finally, XOS is running inside the `xos-1`
+VM and is controlling ONOS and OpenStack. You can get a deeper understanding of
+the configuration of the target server by visiting [head_node_services.md](./head_node_services.md).
+
+## Run the post-deployment tests
+
+After the single-node POD is set up, you can execute a set of basic health
+tests on the platform by running this command:
+
+```
+./gradlew -PdeployConfig=/cord/components/platform-install/config/default.yml post-deploy-tests
+```
+
+Currently this tests the E2E connectivity of the POD by performing the following
+steps:
+ * Setting up a sample CORD subscriber in XOS
+ * Launch a vSG for that subscriber on the CORD POD
+ * Creating a test client, corresponding to a device in the subscriber's household
+ * Connecting the test client to the vSG using a simulated OLT
+ * Running `ping` in the client to a public IP address in the Internet
+
+Success of this test means that traffic is flowing between the subscriber
+household and the Internet via the vSG.
### Optional cleanup
-Exit from the build environment and destroy it:
+Once you are finished deploying the single-node POD, you can exit from the development
+environment on the build host and destroy it:
- ```
- exit
- vagrant destroy -f
- ```
-
+```
+exit
+vagrant destroy -f
+```
### Congratulations
diff --git a/docs/quickstart_physical.md b/docs/quickstart_physical.md
index 7aadc30..110a62e 100644
--- a/docs/quickstart_physical.md
+++ b/docs/quickstart_physical.md
@@ -57,64 +57,13 @@
host outside of the POD.
## Create Development Environment
-The development environment is required for the other tasks in this repository.
-The other tasks could technically be done outside this Vagrant based development
-environment, but it would be left to the user to ensure connectivity and
-required tools are installed. It is far easier to leverage the Vagrant based
-environment.
-### Cloning the Repository
-To clone the repository select a location on the outside the POD (OtP) host and
-issue the `git` command to download (clone) the repository.
-```
-git clone http://gerrit.opencord.org/cord
-```
-When this is complete, a listing (`ls`) of this directory should yield output
-similar to:
-```
-ls
-LICENSE.txt ansible/ components/ gradle/ gradlew.bat utils/
-README.md build.gradle config/ gradle.properties scripts/
-Vagrantfile buildSrc/ docs/ gradlew* settings.gradle
-```
-### Create Development Machine and Head Node Production Server
-To create the development machine the following single Vagrant command can be
-used. This will create an Ubuntu 14.04 LTS based virtual machine and install
-some basic required packages, such as Docker, Docker Compose, and
-Oracle Java 8.
-```
-vagrant up corddev
-```
-**NOTE:** *It may have several minutes for the first command `vagrant up
-corddev` to complete as it will include creating the VM as well as downloading
-and installing various software packages.*
+Follow the instructions in [devel_env_setup.md](./devel_env_setup.md) to set
+up the Vagrant development machine for CORD on your build host outside the
+POD (OtP).
-### Connect to the Development Machine
-To connect to the development machine the following vagrant command can be used.
-```
-vagrant ssh corddev
-```
-
-Once connected to the Vagrant machine, you can find the deployment artifacts
-in the `/cord` directory on the VM.
-```
-cd /cord
-```
-
-### Gradle
-[Gradle](https://gradle.org/) is the build tool that is used to help
-orchestrate the build and deployment of a POD. A *launch* script is included
-in the vagrant machine that will automatically download and install `gradle`.
-The script is called `gradlew` and the download / install will be invoked on
-the first use of this script; thus the first use may take a little longer
-than subsequent invocations and requires a connection to the internet.
-
-### Complete
-Once you have created and connected to the development environment this task is
-complete. The `cord` repository files can be found on the development machine
-under `/cord`. This directory is mounted from the host machine so changes
-made to files in this directory will be reflected on the host machine and
-vice-versa.
+The rest of the tasks in this guide are run from inside the Vagrant development
+machine, in the `/cord` directory.
## Fetch
The fetching phase of the deployment pulls Docker images from the public
@@ -125,7 +74,7 @@
./gradlew fetch
```
-### complete
+### Complete
Once the fetch command has successfully been run, this step is complete. After
this command completes you should be able to see the Docker images that were
downloaded using the `docker images` command on the development machine:
@@ -138,6 +87,7 @@
abh1nav/dockerui latest 6e4d05915b2a 19 months ago 469.5 MB
```
+
## Build Images
Bare metal provisioning leverages utilities built and packaged as Docker
container images. These utilities are: