[SEBA-700] SiaB based development workflow for containers and ONOS Apps
Change-Id: Ieebdba96d25a4e42416ca5e46b219355bfb3e911
diff --git a/SUMMARY.md b/SUMMARY.md
index a7e8fa2..9801480 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -40,9 +40,11 @@
* [Getting the Source Code](developer/getting_the_code.md)
* [Contribute to the documentation](developer/contribute_to_the_docs.md)
* [Modeling Services](developer/xos-intro.md)
- * [Developer Workflows](developer/workflows.md)
+ * Developer Workflows
* [Service Migrations](xos/dev/xosmigrate.md)
- * [Building Docker Images](developer/imagebuilder.md)
+ * [Local Development](developer/workflows/local.md)
+ * [SiaB Development](developer/workflows/siab.md)
+ * [ONOS Apps Development](developer/workflows/onos-apps.md)
* [GUI Development](xos-gui/developer/README.md)
* [Quickstart](xos-gui/developer/quickstart.md)
* [GUI Extensions](xos-gui/developer/gui_extensions.md)
@@ -126,3 +128,4 @@
* [VOLTHA](charts/voltha.md)
* [XOS-CORE](charts/xos-core.md)
* [XOSSH](charts/xossh.md)
+
diff --git a/charts/helm.md b/charts/helm.md
index addf574..dd2e1a2 100644
--- a/charts/helm.md
+++ b/charts/helm.md
@@ -141,7 +141,7 @@
image in a chart.
To handle building and pushing images to a registry, see the [development
-documentation](../developer/workflows.md#pushing-changes-to-a-remote-registry).
+documentation](../developer/workflows/local.md#pushing-changes-to-a-remote-registry).
If you want to change only the registry for one specific image, the easiest way
is to modify the `repository` setting - for example:
diff --git a/developer/contribute_to_the_docs.md b/developer/contribute_to_the_docs.md
index a3caf02..8318116 100644
--- a/developer/contribute_to_the_docs.md
+++ b/developer/contribute_to_the_docs.md
@@ -79,7 +79,7 @@
* [Development Guide](developer/developer.md)
* [Getting the Source Code](developer/getting_the_code.md)
* [Modeling Services](developer/xos-intro.md)
- * [Developer Workflows](developer/workflows.md)
+ * [Developer Workflows](local.md)
* [Service Migrations](xos/dev/xosmigrate.md)
* [Building Docker Images](developer/imagebuilder.md)
* [GUI Development](xos-gui/developer/README.md)
diff --git a/developer/imagebuilder.md b/developer/imagebuilder.md
deleted file mode 100644
index 6dc23bc..0000000
--- a/developer/imagebuilder.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Building Docker Images with imagebuilder
-
-CORD consists of many interrelated Docker images.
-Making sure that the images used in a deployment are consistent with
-the source tree is a challenge we address with a tool called `imagebuilder`.
-`imagebuilder` is currently used to build the XOS, ONOS, and the `mavenrepo`
-(source of ONOS Apps used in CORD) images.
-
-While `imagebuilder` pulls down required images from DockerHub and
-builds/tags images, it does not push those images or delete obsolete
-ones. These tasks are left to other software (Ansible, Jenkins), which
-should take in YAML output from `imagebuilder` and then perform the
-appropriate actions.
-
-## Obtaining and Rebuilding Images
-
-For the normal build process, you won't need to manually download
-images as the `docker-images` make target that runs `imagebuilder`
-will automatically be run as a part of the build process.
-
-If you do need to rebuild images, there is a `make clean-images` target that
-forces `imagebuilder` to be run again and images to be moved into place.
-
-## Adding a new Docker Image to CORD
-
-There are several cases where an Image might need to be added to CORD.
-
-### Adding an Image Developed Outside of CORD
-
-There are cases where a 3rd party image developed outside of CORD may be
-needed. This is the case with ONOS, Redis, and a few other pieces of software
-that are already containerized, and we deploy as-is (or with minor
-modifications).
-
-To do this, add the full name of the image, including a version tag, to the
-`pull_only_images` list in the `docker_images.yml` file. As frequently only a
-subset of this list is needed for a specific helm chart, you can create a YAML
-file with a `docker_image_whitelist` list - see
-`cord/helm-charts/examples/*-images.yaml` for examples.
-
-These images are retagged with a `candidate` tag after being pulled.
-
-### Adding a Synchronizer Image
-
-Adding a synchronizer image is usually as simple as adding it to the
-`buildable_images` list in the `automation-tools/developer/docker_images.yml`
-file.
-
-If you are adding a new service that is not in the repo manifest yet, you may
-have to add your service's directory to the `.repo/manifest.xml` file and then
-list it in `build/docker_images.yml`, so it can build the synchronizer image
-locally.
-
-### Adding Other CORD Images
-
-If you want `imagebuilder` to build an image from a Dockerfile somewhere in the
-CORD source tree, you need to add it to the `buildable_images` list in the
-`docker_images.yml` file (see that file for the specific format), then making
-sure the image name is listed in the `docker_image_whitelist` list.
-
-Note that you don't need to add external parent images to the
-`pull_only_images` in this manner - those are determined by the `FROM` line in
-`Dockerfile`
-
-## Debugging imagebuilder
-
-If you get a different error or think that `imagebuilder` isn't working
-correctly, please rerun it with the `-vv` ("very verbose") option, read through
-the output carefully, and then post about the issue on the mailing list or
-Slack.
-
-If an image is not found on Dockerhub (for example, if you have local
-modifications to the `Dockerfile` or context, or are have a patchset checked
-out), you may see a 404 error like the following in the logs. If this happens,
-imagebuilder will attempt to build the image from scratch rather than pulling
-it:
-
-```python
-NotFound: 404 Client Error: Not Found ("{"message":"manifest for xosproject/xos-gui-extension-builder:<hash> not found"}")
-```
-
-Run `imagebuilder.py -h` for a list of other supported arguments.
-
-## How imagebuilder Works
-
-The `imagebuilder` program performs the following steps when run:
-
-1. Reads the [repo manifest file](https://github.com/opencord/manifest/blob/master/default.xml)
- (checked out as `.repo/manifest`) to get a list of the CORD git repositories.
-
-2. Reads the `automation-tools/developer/docker_images.yml` file and optionally
- a filter file with a `docker_image_whitelist` list.
-
-3. For every container that is needed, reads the Dockerfile and determines if
- any parent images are needed, and creates a tree to order image building.
-
-4. Determines which images need to be rebuilt based on:
-
- * Whether the image exists and has current tags on it. If an image is
- tagged with the `candidate` tag, but shouldn't be this tag is removed.
- * If the Docker build context is *dirty* or differs (is on a different
- branch) from the git tag specified in the repo manifest
- * If the image's parent (or grandparent, etc.) needs to be rebuilt
-
-5. Using this information downloads (pulls) or builds images as needed in a
- way that is consistent with the CORD source that is on disk. If an image
- build is needed, the Docker output of that build is saved to
- `build/image_logs` on the system where Imagebuilder executes (the
- `buildhost` in inventory).
-
-6. Tags the image with the `candidate` and (if clean) git hash tags.
-
-7. Creates a YAML output file that describes the work it performed, for later
- use (pushing images, retagging, etc.), and optional a graphviz `.dot` graph
- file showing the relationships between images.
-
-## Image Tagging
-
-CORD container images frequently have multiple tags. The two most
-common tags are:
-
-* The string `candidate`, which says that the container is ready to be deployed
- on a CORD POD
-* The git commit hash, which is either pulled from DockerHub, or applied when a
- container is built from an untouched (according to git) source tree. Images
- built from a modified source tree will not be tagged in this way.
-
-`imagebuilder` use this git hash tag as well as labels on the image of the git
-repos of parent images to determine whether an image is correctly built from
-the checked out source tree.
-
-## Image Labels
-
-`imagebuilder` uses a Docker label scheme to determine whether an
-image needs to be rebuilt, which is added to the image when it is
-built. Docker images used in CORD must apply labels in their
-Dockerfiles which are specified by
-[label-schema.org](http://label-schema.org); look there for examples,
-and below for a few notes that clear up the ambiguity within that spec.
-
-Required labels for every CORD image:
-
-* `org.label-schema.version`
-* `org.label-schema.name`
-* `org.label-schema.vcs-url`
-* `org.label-schema.build-date`
-
-Required for clean builds:
-
-* `org.label-schema.version` : *git branch name, ex: `opencord/master`,
- `opencord/cord-4.0`, , etc.*
-* `org.label-schema.vcs-ref` : *the full 40 character SHA-1 git commit hash,
- not shortened*
-
-Required for dirty builds:
-
-* `org.label-schema.version` : *set to the string `dirty` if there is any
- differences from the master commit to the build context (either on a
- different branch, or untracked/changed files in context)*
-* `org.label-schema.vcs-ref` - *set to a commit hash if build context is clean
- (ie, on another unnamed branch/patchset), or the empty string if the build
- context contains untracked/changed files.*
-
-For images that use components from another repo (like chameleon being
-integrated with the XOS containers, or maven repo which contains artifacts from
-multiple onos-apps repos), the following labels should be set for every
-sub-component, with the repo name (same as org.label-schema.name) replacing
-`<reponame>`, and the value being the same value as the label-schema
-one would be:
-
-* `org.opencord.component.<reponame>.version`
-* `org.opencord.component.<reponame>.vcs-ref`
-* `org.opencord.component.<reponame>.vcs-url`
-
-These labels are applied by using the `ARG` and `LABEL` option in the
-Dockerfile. The following is an example set of labels for an image that uses
-files from the chameleon and XOS repositories as components:
-
-```dockerfile
-# Label image
-ARG org_label_schema_schema_version=1.0
-ARG org_label_schema_name=openstack-synchronizer
-ARG org_label_schema_version=unknown
-ARG org_label_schema_vcs_url=unknown
-ARG org_label_schema_vcs_ref=unknown
-ARG org_label_schema_build_date=unknown
-ARG org_opencord_vcs_commit_date=unknown
-ARG org_opencord_component_chameleon_version=unknown
-ARG org_opencord_component_chameleon_vcs_url=unknown
-ARG org_opencord_component_chameleon_vcs_ref=unknown
-ARG org_opencord_component_xos_version=unknown
-ARG org_opencord_component_xos_vcs_url=unknown
-ARG org_opencord_component_xos_vcs_ref=unknown
-
-LABEL org.label-schema.schema-version=$org_label_schema_schema_version \
- org.label-schema.name=$org_label_schema_name \
- org.label-schema.version=$org_label_schema_version \
- org.label-schema.vcs-url=$org_label_schema_vcs_url \
- org.label-schema.vcs-ref=$org_label_schema_vcs_ref \
- org.label-schema.build-date=$org_label_schema_build_date \
- org.opencord.vcs-commit-date=$org_opencord_vcs_commit_date \
- org.opencord.component.chameleon.version=$org_opencord_component_chameleon_version \
- org.opencord.component.chameleon.vcs-url=$org_opencord_component_chameleon_vcs_url \
- org.opencord.component.chameleon.vcs-ref=$org_opencord_component_chameleon_vcs_ref \
- org.opencord.component.xos.version=$org_opencord_component_xos_version \
- org.opencord.component.xos.vcs-url=$org_opencord_component_xos_vcs_url \
- org.opencord.component.xos.vcs-ref=$org_opencord_component_xos_vcs_ref
-```
-
-Labels on a built image can be seen by running `docker inspect <image name or id>`
-
-## Automating Image Builds
-
-There is a [Jenkinsfile.imagebuilder](https://github.com/opencord/cord/blob/{{
-book.branch }}/Jenkinsfile.imagebuilder) that can be run in a Jenkins
-instance and will build and push images to DockerHub. This is how the CORD
-team pre-builds and publishes images for public use.
-
diff --git a/developer/workflows.md b/developer/workflows/local.md
similarity index 81%
rename from developer/workflows.md
rename to developer/workflows/local.md
index ba1fb7a..b3afe5d 100644
--- a/developer/workflows.md
+++ b/developer/workflows/local.md
@@ -1,4 +1,4 @@
-# Developer Workflows
+# Local Development
This section describes a typical workflow for developing the CORD
control plane. This workflow does not include any data plane
@@ -9,7 +9,7 @@
It is straightforward to set up a local Kubernetes environment on your laptop.
The recommended way to do this is to use Minikube. This guide assumes
you have done that. See the
-[Single-Node](../prereqs/k8s-single-node.md) case in the
+[Single-Node](../../prereqs/k8s-single-node.md) case in the
Installation Guide for more information, or you can go directly
to the documentation for Minikube:
<https://kubernetes.io/docs/getting-started-guides/minikube/#installation>
@@ -32,15 +32,15 @@
In this folder you can choose from the different charts which one to
deploy. For example to deploy SEBA you can follow
-[these instructions](../profiles/seba/install.md). Alternatively, if
+[these instructions](../../profiles/seba/install.md). Alternatively, if
you are working on a new profile or a new service that is not part of
any existing profile, you can install just the
-[CORD Platform](../installation/platform.md).
+[CORD Platform](../../installation/platform.md).
## Making and Deploying Changes
Assuming you have
-[downloaded the CORD source code](getting_the_code.md) and the entire
+[downloaded the CORD source code](../getting_the_code.md) and the entire
source tree for CORD is under `~/cord`, you can edit and re-deploy the
code as follows.
@@ -56,19 +56,18 @@
eval $(minikube docker-env)
```
-You will then need to build the containers from source:
+You will then need to build the containers from source, so enter the repo you modified:
```shell
-cd ~/cord/automation-tools/developer
-python imagebuilder.py -f ../../helm-charts/examples/filter-images.yaml -x
+cd ~/cord/orchestration/xos-services/rcord
+DOCKER_REPOSITORY=xosproject/ DOCKER_TAG=candidate make docker-build
```
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.
+> **Note:** In some cases the command to build the docker image may vary.
+> Please check the Makefile within the repo for more informations.
All that is left is to teardown and re-deploy the containers.
@@ -94,6 +93,6 @@
The way we recommend doing this is via a private docker registry.
You can find more information about what a docker registry is in the
-[offline installation section](../installation/offline-install.md).
+[offline installation section](../../installation/offline-install.md).
{% include "/partials/push-images-to-registry.md" %}
diff --git a/developer/workflows/onos-apps.md b/developer/workflows/onos-apps.md
new file mode 100644
index 0000000..105276a
--- /dev/null
+++ b/developer/workflows/onos-apps.md
@@ -0,0 +1,132 @@
+# Developing ONOS Applications with SEBA in a Box
+
+This tutorial will guide you through the development workflow for ONOS applications in SEBA.
+The `aaa` application will be used as an example, but the same workflow is valid for any
+ONOS application.
+
+### Requirements
+
+In order to follow this tutorial you need to:
+
+- have a remote machine to run [SEBA-in-a-Box](../../profiles/seba/siab.md)
+- have the Java SDK installed on your development machine
+- have the CORD code (we suggest to download the code using [this guide](../getting_the_code.md#download-cord-repositories))
+
+{% include "/partials/siab-short.md" %}
+
+## Test applications on a running setup
+
+We assume you already have done changes to your application code and that you need to build it and push it
+to a running ONOS.
+
+To build the application, just enter the appropriate folder and invoke the `maven` target:
+
+```bash
+cd ~/cord/onos-apps/apps/aaa/
+mvn clean install
+```
+
+Once the application is built, you can push it to ONOS using the `onos-app` command:
+
+```bash
+onos-app -P 30120 -u karaf -p karaf <myregistrydomain.com> reinstall! org.opencord.aaa app/target/aaa-app-1.10.0-SNAPSHOT.oar
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+If the commands succeed you should see an output similar to:
+
+```bash
+{"name":"org.opencord.aaa","id":173,"version":"1.10.0.SNAPSHOT","category":"Traffic Steering","description":"802.","readme":"802.1x authentication service.","origin":"ON.Lab","url":"http://onosproject.org","featuresRepo":"mvn:org.opencord/aaa-app/1.10.0-SNAPSHOT/xml/features","state":"ACTIVE","features":["aaa-app"],"permissions":[],"requiredApps":["org.opencord.sadis"]}
+```
+
+**Important!!**
+
+Please remember that the application `.oar` can be generated in a different
+location depending on the application structure and that the version included in the SNAPSHOT file name can differ.
+
+> You can get the `onos-app` command you can get it [here](https://github.com/opennetworkinglab/onos/blob/onos-1.13/tools/package/runtime/bin/onos-app)
+> and add it to your `$PATH`
+
+## Deploy SiaB using development applications
+
+In certain cases you want to deploy SEBA-in-a-box automatically including your development applications,
+for example to verify that the end to end flow is correctly working.
+
+In order to do that you need to:
+
+- make your applications available somewhere for ONOS to download them
+- customize the ONOS applications URL in the helm charts
+
+We suggest to create a `nginx` container and deploy it on top of the kubernetes cluster, but if have a company
+web-server that is reachable by ONOS that can be a viable option.
+
+### Build the mavenrepo container
+
+A `Dockerfile` to build a `nginx` web-server containing development `.oar`s is provided with the code.
+You can build such container by:
+
+```bash
+cd ~/cord/onos-apps
+docker build -t opencord/mavenrepo:candidate -f Dockerfile.apps .
+...
+Successfully built fda11faac37f
+Successfully tagged opencord/mavenrepo:candidate
+```
+
+#### Deploy the mavenrepo container on top of your cluster
+
+> NOTE that this step requires a `docker-registry` to be installed in the cluster.
+> If you don't have it, you can follow [these instructions](./siab.md#deploy-a-docker-registry).
+
+Once the container is build, you can push it to the remote `docker-registry` using these commands:
+
+```bash
+docker tag opencord/mavenrepo:candidate myregistrydomain.com:30500/opencord/mavenrepo:candidate
+docker push myregistrydomain.com:30500/opencord/mavenrepo:candidate
+The push refers to repository [myregistrydomain.com:30500/opencord/mavenrepo]
+2781364a4526: Pushed
+8a32ae098140: Pushed
+7c9c7be9dce0: Pushed
+9a6bd1609bff: Pushed
+77e23640b533: Pushed
+757d7bb101da: Pushed
+3358360aedad: Pushed
+candidate: digest: sha256:38788909e84ffb955a41fd14eea9c19f4596bb9b3b7f3181a1332499b7709b94 size: 1786
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+Once the container is loaded in the `docker-registry` you can you `helm` to deploy it from the SiaB host machine:
+
+```bash
+cd ~/cord/helm-charts
+helm install -n mavenrepo cord/mavenrepo --set image.tag=candidate \
+--set image.repository=myregistrydomain.com:30500/opencord/mavenrepo
+```
+
+#### Customize the ONOS applications URL in the helm charts
+
+In order to install custom versions of the application during the installation process, you need to create
+a value file called `~/custom.yaml` (on the SiaB host machine) with the following values:
+
+
+>If you already have a value file to specify other container images you can simply extend that one
+
+
+```yaml
+aaaAppUrl: "myregistrydomain.com:30160/repository/aaa-app-1.10.0-SNAPSHOT.oar"
+aaaAppVersion: "1.10.0.SNAPSHOT"
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+You can then install SEBA-in-a-box with:
+
+```bash
+SEBAVALUES=~/custom.yaml make
+```
+
+> You can find a full list of the application names and URLs here:
+> - https://github.com/opencord/helm-charts/blob/master/xos-profiles/seba-services/values.yaml#L43-L53
+> - https://github.com/opencord/helm-charts/blob/master/workflows/att-workflow/values.yaml#L40-L41
\ No newline at end of file
diff --git a/developer/workflows/siab.md b/developer/workflows/siab.md
new file mode 100644
index 0000000..a56d5d6
--- /dev/null
+++ b/developer/workflows/siab.md
@@ -0,0 +1,257 @@
+# SEBA in a Box for development
+
+This tutorial will guide you through the development workflow for a SEBA component using
+the environment provided by SEBA in a Box.
+
+The tutorial will use the `rcord` service as an example, but the same workflow can be used
+for each docker-based component in SEBA.
+
+If you are working on ONOS applications, you want to take a look at this [tutorial](./onos-apps.md).
+
+> NOTE that the same workflow can be adapted for:
+> - different emulated environment (eg: `MCORD in a Box`)
+> - physical setups
+
+### Requirements
+
+In order to follow this tutorial you need to:
+
+- have a remote machine to run [SEBA-in-a-Box](../../profiles/seba/siab.md)
+- have Docker installed on your development machine (Install docker on [Mac](https://docs.docker.com/docker-for-mac/install/), [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/) or [Windows](https://docs.docker.com/docker-for-windows/install/))
+- have the CORD code (we suggest to download the code using [this guide](../getting_the_code.md#download-cord-repositories))
+
+{% include "/partials/siab-short.md" %}
+
+## Deploy a docker registry
+
+In order to move Docker images from your laptop to the SEBA in a Box environment you need
+a Docker registry. You can install one using `helm`:
+
+```bash
+helm install stable/docker-registry --set service.nodePort=30500,service.type=NodePort -n docker-registry
+```
+
+### Configure docker to push to an insecure registry
+
+The registry deployed via `helm` is by default an insecure registry (it uses `http` instead of `https`)
+thus `docker` requires that you explicitly authorize that registry.
+
+You can find more informations about insecure registries on the [docker documentation](https://docs.docker.com/registry/insecure/).
+
+#### MacOS
+
+To open the `Docker` preferences click on the icon in the status bar (top right of the screen)
+and select `preferences`.
+
+Navigate to the `Daemon` tab and under `Insecure registries` add the `ip` and `port` of the one
+running on your `SiaB` machine:
+
+
+
+> NOTE that the docker-registry endpoint should be `myregistrydomain.com:30500`
+> where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+Click on `Apply and Restart` to apply your changes.
+
+#### Linux
+
+> This needs to be done on the SiaB machine (and on you machine if it's a Linux based machine)
+
+Edit the `/etc/docker/daemon.json` file and add:
+
+```json
+{
+ "insecure-registries" : ["myregistrydomain.com:30500"]
+}
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+Then restart the docker daemon with: `sudo service docker restart`
+
+## Make changes and publish the image
+
+Once you make the appropriate changes to the code, you can buid it with:
+
+```bash
+cd ~/cord/orchestration/xos-services/rcord
+DOCKER_REGISTRY=myregistrydomain.com:30500/ DOCKER_REPOSITORY=xosproject/ DOCKER_TAG=candidate make docker-build
+...
+Successfully built 14a4ec8f2906
+Successfully tagged myregistrydomain.com/xosproject/rcord-synchronizer:candidate
+```
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+> **Note:** In some cases the command to build the docker image may vary.
+> Please check the Makefile within the repo for more informations.
+
+To push the newly built image to your docker registry use this command:
+
+```bash
+cd ~/cord/orchestration/xos-services/rcord
+DOCKER_REGISTRY=myregistrydomain.com:30500/ DOCKER_REPOSITORY=xosproject/ DOCKER_TAG=candidate make docker-push
+docker push myregistrydomain.com:30500/xosproject/rcord-synchronizer:candidate
+The push refers to repository [myregistrydomain.com:30500/xosproject/rcord-synchronizer]
+43b4d40e8ced: Layer already exists
+70019539cd35: Layer already exists
+56585fbf0fe2: Layer already exists
+4929606216d8: Layer already exists
+343eab13e1e3: Layer already exists
+ea7c8d4e60dc: Layer already exists
+7d63eb9a32c4: Layer already exists
+bcf2f368fe23: Layer already exists
+candidate: digest: sha256:f5ecac2ba76c2a81a6f8b82b09e07c53f9ca2f3d272c8861ed7f5ed1ac290ac8 size: 1993
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+## Customizing the installation
+
+When `SiaB` is installed with the `make latest` command, a [`values.yaml`](https://github.com/opencord/helm-charts/blob/master/configs/seba-ponsim-latest.yaml) file is applied
+to all the `helm install` commands.
+
+> To know more about `values` files, please check the official [helm documentation](https://helm.sh/docs/chart_template_guide/#values-files)
+
+To customize the installation, download the default `seba-ponsim-latest.yaml` so that you can customize it:
+
+```bash
+curl https://raw.githubusercontent.com/opencord/helm-charts/master/configs/seba-ponsim-latest.yaml -o ~/custom.yaml
+```
+
+### Update the helm chart
+
+To deploy the new container you need to update the helm-chart, but first you need to customize the
+value file.
+
+Open the file you downloaded in `~/custom.yaml` and change the `rcord` section so that it looks like:
+
+```yaml
+rcord:
+ image:
+ repository: "myregistrydomain.com:30500/xosproject/rcord-synchronizer"
+ tag: 'candidate'
+```
+
+The `rcord` service is installed by the `seba-services` helm chart, so you need to upgrade it to
+the new version:
+
+```bash
+cd ~/cord/helm-charts
+helm upgrade --install seba-services xos-profiles/seba-services -f ~/custom.yaml
+```
+
+> NOTE it's important that you upgrade the chart defining the component you are developing.
+> For more informations about the helm charts visit the [Helm reference](../../charts/helm.md) section in the guide.
+
+### Reinstall from scratch
+
+In some cases you want to restart from a clean environment using your images.
+If you do that it is important not to run the `make reset-kubeadm` command as that will
+completely teardown kubernetes, deleting the docker registry.
+
+To remove all the installed containers you can instead use the `make teardown-charts` commands.
+
+Once all the containers have been removed, you can reinstall everything using your value file with:
+
+```bash
+SEBAVALUES=~/custom.yaml make
+```
+
+> NOTE that the `latest` target is not needed as we are specifying a custom value file through the `SEBAVALUES` variable.
+
+## Troubleshooting
+
+If you are facing issues with this development workflow, please report your problem on the [SEBA-dev](https://groups.google.com/a/opennetworking.org/forum/#!forum/seba-dev)
+or [CORD-dev](https://groups.google.com/a/opencord.org/forum/#!forum/cord-dev) mailing lists, or contact `@teone` on slack.
+
+## FAQs
+
+### I want to update an image that comes from a different chart, how do I know the value file structure?
+
+If you're not familiar with how value files work we suggest to read the [official documentation](https://helm.sh/docs/chart_template_guide/#values-files)
+but to make it short you can look for the `values.yaml` file in the helm chart you are working with.
+
+> If the helm chart is installed as a requirement of another chart also look for the requirement name
+> in the parent chart. For example the `rcord` chart is installed as part of [`seba-services`](https://github.com/opencord/helm-charts/blob/master/xos-profiles/seba-services/requirements.yaml#L17-L19)
+> and that's why we nest the customization under `rcord`.
+
+### Why do I need a remote docker-registry?
+
+We have a talk about this topic during ONF Connect 2018, you can find the recording [here](https://vimeo.com/307548812/cf9c31e226)
+and the slides [here](https://www.opennetworking.org/wp-content/uploads/2018/12/How-the-New-Platform-Will-Make-Your-Life-Better.pdf).
+
+To explain that in few words, you need a way to move the docker image from the "build" machine to the "host" machine,
+as described in the picture below.
+
+
+
+#### I don't want to use a private docker-registry, can I use Docker Hub?
+
+If you don't want to deploy a docker-registry on the POD, you can use any docker registry.
+The `docker-build/docker-push` commands are flexible enough to accomodate that,
+for example you can build and push the container with these commands:
+
+```bash
+DOCKER_REPOSITORY=matteoscandolo/ DOCKER_TAG=candidate make docker-build
+DOCKER_REPOSITORY=matteoscandolo/ DOCKER_TAG=candidate make docker-push
+```
+
+And customize your value file to fetch that image:
+
+```yaml
+rcord:
+ image:
+ repository: "matteoscandolo/rcord-synchronizer"
+ tag: 'candidate'
+```
+
+#### Can I build images on the SiaB machine and use those?
+
+Yes, you can build the docker containers directly on the SiaB host machine, just be aware that this workflow won't
+transfer to a multi-node cluster.
+
+If you build the `rcord-synchronizer` docker image on the SiaB machine with:
+
+```bash
+DOCKER_REPOSITORY=xosproject/ DOCKER_TAG=candidate make docker-build
+```
+
+you can change the `custom.yaml` value file in this way to use it:
+
+```yaml
+rcord:
+ image:
+ tag: 'candidate'
+ pullPolicy: 'IfNotPresent'
+```
+
+> For more information about this workflow we suggest to take a look at the talk mentioned in the [Why do I need a remote docker-registry?](./siab.md#why-do-i-need-a-remote-docker-registry) section.
+
+### Can use the same workflow to test VOLTHA images?
+
+Yes, the workflow to test VOLTHA images is absolutely the same, but some of the commands are different.
+
+On your local machine you can build VOLTHA images with:
+
+```bash
+cd ~/cord/incubator/voltha
+REPOSITORY=voltha/ TAG=candidate VOLTHA_BUILD=docker make build
+```
+
+Then you need to tag and push the images you want to upload with:
+
+```bash
+docker tag voltha/voltha-voltha:candidate myregistrydomain.com:30500/voltha/voltha-voltha:candidate
+docker push myregistrydomain.com:30500/voltha/voltha-voltha:candidate
+```
+
+where `myregistrydomain.com` is the public `ip` of your `SiaB` machine.
+
+And update you `custom.yaml` value file on the SiaB machine with:
+
+```yaml
+images:
+ vcore:
+ repository: "myregistrydomain.com:30500/voltha/voltha-voltha"
+ tag: 'candidate'
+```
\ No newline at end of file
diff --git a/images/docker-registry.png b/images/docker-registry.png
new file mode 100644
index 0000000..2096aab
--- /dev/null
+++ b/images/docker-registry.png
Binary files differ
diff --git a/images/docker_config_mac_os.png b/images/docker_config_mac_os.png
new file mode 100644
index 0000000..742ac49
--- /dev/null
+++ b/images/docker_config_mac_os.png
Binary files differ
diff --git a/partials/siab-short.md b/partials/siab-short.md
new file mode 100644
index 0000000..81bdcc4
--- /dev/null
+++ b/partials/siab-short.md
@@ -0,0 +1,15 @@
+## Preparing SEBA in a Box
+
+We suggest to refer to [this](../../profiles/seba/siab.md) guide to deploy SEBA in a Box, but for simplicity
+the commands are replicated here:
+
+```bash
+mkdir -p ~/cord
+cd ~/cord
+git clone https://gerrit.opencord.org/automation-tools
+cd automation-tools/seba-in-a-box
+make latest
+```
+
+> NOTE that for development we suggest do use the `latest` available version of all the components,
+> but in certain cases (eg: bugfixes) you may want to use `make stable`
\ No newline at end of file
diff --git a/styles/website.css b/styles/website.css
index 42ecd82..44e4555 100644
--- a/styles/website.css
+++ b/styles/website.css
@@ -18,4 +18,5 @@
border: 1px solid rgba(0, 0, 0, 0.07);
border-radius: 3px;
padding: 0 20px !important;
+ margin-top: 150px;
}
\ No newline at end of file
