Adding developer workflow documentation
Change-Id: Ie0fea2f80cb8aa9ca23e7653b1bc6163e7bbc5d2
diff --git a/SUMMARY.md b/SUMMARY.md
index 8592f15..a9f3586 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -10,7 +10,7 @@
* [Helm](prereqs/helm.md)
* [Docker Registry](prereqs/docker-registry.md)
* [OpenStack Integration](prereqs/openstack-helm.md)
- * [Profiles](profiles.md)
+ * [Profiles](profiles/intro.md)
* [RCORD Lite](profiles/rcord-lite.md)
* [OLT Setup](profiles/olt-setup.md)
* [MCORD](profiles/mcord.md)
@@ -20,7 +20,7 @@
* [ONOS](charts/onos.md)
* [VOLTHA](charts/voltha.md)
* [Fabric setup](prereqs/fabric-setup.md)
-* [Operating CORD](operating_cord/intro.md)
+* Operating CORD
* [Diagnostics](operating_cord/diag.md)
* [Defining Models in CORD](xos/README.md)
* [XOS Support for Models](xos/dev/xproto.md)
@@ -29,9 +29,9 @@
* [Writing Synchronizers](xos/dev/synchronizers.md)
* [Design Guidelines](xos/dev/sync_arch.md)
* [Implementation Details](xos/dev/sync_impl.md)
-* [Developing for CORD](develop.md)
- * [Getting the Source Code](getting_the_code.md)
- * [Developer Workflows](workflows.md)
+* Developing for CORD
+ * [Getting the Source Code](developer/getting_the_code.md)
+ * [Developer Workflows](developer/workflows.md)
* [VTN and Service Composition](xos/xos_vtn.md)
* [GUI Development](xos-gui/developer/README.md)
* [Quickstart](xos-gui/developer/quickstart.md)
diff --git a/develop.md b/develop.md
deleted file mode 100644
index 402fa27..0000000
--- a/develop.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Developing for CORD
-
-This guide describes how to develop for CORD. It includes several example
-developer workflows, a tour of an example service, an overview of how
-services are interconnected in the data plane, and in-depth
-descriptions of how to develop/extend the TOSCA and GUI interfaces.
diff --git a/getting_the_code.md b/developer/getting_the_code.md
similarity index 92%
rename from getting_the_code.md
rename to developer/getting_the_code.md
index 90fb8b1..4c3d308 100644
--- a/getting_the_code.md
+++ b/developer/getting_the_code.md
@@ -30,7 +30,7 @@
{% include "/partials/repo-download.md" %}
-> NOTE: `-b` specifies the branch name. Development work goes on in `master,
+> NOTE: `-b` specifies the branch name. Development work goes on in `master`,
> and there are also specific stable branches such as `cord-4.0` that can be
> used.
@@ -39,7 +39,8 @@
```sh
$ ls
-build component incubator onos-apps orchestration test
+automation-tools component helm-charts onos-apps subscriber.yaml
+build docs incubator orchestration test
```
## Download patchsets
diff --git a/developer/workflows.md b/developer/workflows.md
new file mode 100644
index 0000000..de2c2bc
--- /dev/null
+++ b/developer/workflows.md
@@ -0,0 +1,97 @@
+# Developer Workflows
+
+This document is intended to describe the workflow to
+develop the control plane of CORD.
+
+## Setting up a local development environment
+
+The first thing you’ll need to work on the control plane of CORD, known as XOS,
+is to setup a local Kubernetes environment.
+The suggested way to achieve that is to use Minikube on your laptop,
+and this guide assume that it will be the environment going forward.
+
+You can follow this guide to get started with Minikube:
+<https://kubernetes.io/docs/getting-started-guides/minikube/#installation>
+
+> Note: If you are going to do development on Minikube you may want to
+>increase it’s memory from the default 512MB,
+>you can do that using this command to start Minikube:
+>`minikube start --cpus 2 --memory 4096`
+
+Once Minikube is up and running on your laptop you can proceed with
+the following steps to bring XOS up.
+
+Once Minikube is installed you’ll need to install Helm:
+<https://docs.helm.sh/using_helm/#installing-helm>
+
+At this point you should be able to deploy the core components of XOS
+and the services required by R-CORD from images published on dockerhub.
+
+> NOTE: You can replace the `xos-profile` with the one you need to work on.
+
+```shell
+cd ~/cord/build/helm-charts
+helm install xos-core -n xos-core
+helm dep update xos-profiles/rcord-lite
+helm install xos-profiles/rcord-lite -n rcord-lite
+```
+
+## Making changes and deploy them
+
+You can follow this guide to [get the CORD source code](getting_the_code.md).
+
+We assume that now you have the entire CORD tree under `~/cord`
+
+> Note: to develop a single synchronizer you may not need the full CORD source,
+but this assume that you have a good knowledge of the system and
+you know what you’re doing.
+
+As first you’ll need to point Docker to the one provided by Minikube
+(_note that you don’t need to have docker installed,
+as it comes with the Minikube installation_).
+
+```shell
+eval $(minikube docker-env)
+```
+
+Then you’ll need to build the XOS containers from source:
+
+```shell
+cd ~/cord/build
+python scripts/imagebuilder.py -f helm-charts/examples/filter-images.yaml
+```
+
+At this point the images containing your changes will be available
+in the Docker environment used by Minikube.
+
+> Note: in some cases you can rebuild a single docker image to make
+the process faster, but this assume that you have a good knowledge of the system
+and you know what you’re doing.
+
+All that is left is to teardown and redeploy the containers.
+
+```shell
+helm del --purge xos-core
+helm del --purge rcord-lite
+helm install xos-core -n xos-core -f examples/candidate-tag-values.yaml -f examples/if-not-present-values.yaml
+helm dep update xos-profiles/rcord-lite
+helm install xos-profiles/rcord-lite -n rcord-lite -f examples/candidate-tag-values.yaml -f examples/if-not-present-values.yaml
+```
+
+In some cases is possible to use the helm upgrade command,
+but if you made changes to the models we suggest to redeploy everything
+
+> Note: if your changes are only in the synchronizer steps,
+after rebuilding the containers, you can just delete the corresponding POD
+and kubernetes will restart it with the new image
+
+## Pushing changes to a remote registry
+
+If you have a remote POD you want to test your changes on, you need to push your
+docker images on a registry that can be accessed from the POD itself.
+
+The way we suggest to do this is via a private docker-registry,
+you can find more informations about what a
+docker-registry is [here](../prereqs/docker-registry.md).
+
+{% include "/partials/push-images-to-registry.md" %}
\ No newline at end of file
diff --git a/operating_cord/intro.md b/operating_cord/intro.md
deleted file mode 100644
index 49966c6..0000000
--- a/operating_cord/intro.md
+++ /dev/null
@@ -1 +0,0 @@
-# Operating CORD
\ No newline at end of file
diff --git a/partials/push-images-to-registry.md b/partials/push-images-to-registry.md
new file mode 100644
index 0000000..8a91498
--- /dev/null
+++ b/partials/push-images-to-registry.md
@@ -0,0 +1,25 @@
+Once you have your registry set up, you'll need to tag you images adding the
+registry address.
+
+Supposing your docker-registry address is:
+
+```shell
+192.168.10.12:30500
+```
+
+and that your image name is:
+
+```shell
+xosproject/vsg-synchronizer
+```
+
+You'll need to re-tag the image as
+
+```shell
+192.168.10.12:30500/xosproject/vsg-synchronizer
+```
+
+> NOTE: you can do that using the `docker tag` command:
+> ```shell
+> docker tag xosproject/vsg-synchronizer:candidate 192.168.10.12:30500/xosproject/vsg-synchronizer:candidate
+> ```
\ No newline at end of file
diff --git a/prereqs/docker-registry.md b/prereqs/docker-registry.md
index d5e2fc0..f6a7e20 100644
--- a/prereqs/docker-registry.md
+++ b/prereqs/docker-registry.md
@@ -1,5 +1,37 @@
# Docker Registry
-Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ea molestiae quisquam
-non praesentium fuga at quod pariatur quis, illo. Incidunt doloremque at
-provident accusamus totam sint quibusdam repudiandae veniam recusandae.
+This guide will help you in deploying an insecure `docker-registry`.
+The tipical usecases for such registry are development, POCs or lab trials.
+
+**Please be aware that this is NOT intended for production use**
+
+## What is a docker registry?
+
+If you have ever used docker, for sure you have used a docker registry.
+The most used `docker-registry` is the default public one: `hub.docker.com`
+
+In certain cases, such as development or when the public registry is not
+reachable, you may want to setup a private version on it, to push and pull
+your images in a more controlled way.
+
+For more information about docker registries, please take a look
+at the [official documentation](https://docs.docker.com/registry/).
+
+## Deploy an insecure docker registry on top of Kubernets
+
+We suggest to use the official helm-chart to deploy a docker-registry,
+and this command will deploy it and expose it on port `30500`:
+
+```shell
+helm install stable/docker-registry --set service.nodePort=30500,service.type=NodePort -n docker-registry
+```
+
+> In any moment you can check the images available on your registry with this
+> command:
+> ```shell
+> curl -X GET https://KUBERNETES_IP:30500/v2/_catalog
+> ```
+
+## Push the images to the docker registry
+
+{% include "/partials/push-images-to-registry.md" %}
\ No newline at end of file
diff --git a/profiles.md b/profiles/intro.md
similarity index 100%
rename from profiles.md
rename to profiles/intro.md
diff --git a/workflows.md b/workflows.md
deleted file mode 100644
index 06a2c74..0000000
--- a/workflows.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Developer Workflows
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit. Neque optio, ea error
-tenetur mollitia, repellendus consectetur iste hic molestias autem odio minima
-doloremque at sunt recusandae fugiat quidem quo architecto.
-