updated "demo setup" instructions and dev. guide to provide more clea…

…r instructions

README.md

@@ -56,11 +56,19 @@ scenarios.
 **Note:** the Docker Hub repository mentioned above is not the official project repository from Eclipse Foundation.
 ***
 
-Suppose the target is the current snapshot 2.0.0-SNAPSHOT.
-
 * Clone Eclipse Kapua™ into a local directory
 * Open an OS shell and move to Kapua project root directory
 * Start Docker runtime
+
+The Kapua repository mentioned above hosts only images of released versions. It is possible to test different versions of Kapua doing a checkout into
+the release branches (for example, "release-1.6.x") and to the tagged commits to select the specific version (for example, the commit tagged as "1.6.7"). Doing so, it is assured
+that the following step will pull proper images from the Docker Hub. If, on the other hand, your target is a SNAPSHOT version (for example, the 2.0.0-SNAPSHOT), a local build is required
+in order to create the docker images and proceed to the next step. Instructions for building can be found in the building.md file under the path docs/developer-guide.
+Assuming that your interest is to deploy a release before 2.0.0 and that you want to pull images from the Docker Hub, it is important to set now the
+`IMAGE_VERSION` environment variable with a value equal to the target version. For example, in the case of the 1.6.7
+
+    export IMAGE_VERSION=1.6.7
+
 * Start Kapua:
 
 On Linux/MacOS:
@@ -77,12 +85,6 @@ On Windows (PowerShell):
 
 The command starts all the Kapua containers using Docker Compose.
 
-By default, the `latest` version of images will be used. If you want to run some other version of Kapua, set the `IMAGE_VERSION` environment variable, for example:
-
-```bash
-    export IMAGE_VERSION=0.2.0
-```
-
 You can check if the containers are running by typing the following command:
 
 ```bash

docs/developer-guide/en/building.md

@@ -4,15 +4,9 @@ We use Apache Maven as the build tool of choice.
 
 We use `gitbook` to build the documentation.
 
-## How to build
+## Tests execution
 
-Kapua is being compiled with Maven.
-
-There are 3 build options you can use, based on the need to perform the various tests, these are now reported in ascending order of building times.
-
-#### Build without tests
-
-   `mvn clean install -DskipTests`
+This section instructs how to execute locally project's tests, if you are not interested (for example, considering that these tests are part of the GitHub CI process) you can skip to the next section
 
 #### Build executing unit tests
 
@@ -43,6 +37,26 @@ NOTE: It is important to launch the script being in the "Kapua" root folder, in
 
 Launch it in order to build Kapua executing all the tests. Integration tests are divided by category to offer maximum error-check-granularity. 
 
+## Docker images building
+
+Keep in mind that Kapua Docker images are hosted under [Kapua DockerHub account](https://hub.docker.com/r/kapua/). 
+If your interest is to build Kapua Docker images by yourself, and you didn't do it in the previous step, execute Maven build with `docker` profile enabled:
+
+    mvn clean install -Pdocker -DskipTests
+
+Add the `console` profile to generate also the Web Console docker image:
+
+    mvn clean install -Pdocker,console -DskipTests
+
+If you want to speed up the build process you can ask Maven to ignore `-SNAPSHOT` updates
+force it to use only locally present artifacts with the `dev` profile.
+
+    mvn clean install -Pdocker,dev -DskipTests
+
+Again, don't forget the `console` profile if the Web Console image is needed:
+
+    mvn clean install -Pdocker,dev,console -DskipTests
+
 ## Security Scan
 
 You can perform the CVE scan of the project by running with the following command:
@@ -103,28 +117,7 @@ We also use CI server sponsored by [Red Hat](https://www.redhat.com/en) to autom
 [Kapua DockerHub account](https://hub.docker.com/r/kapua/). Red Hat CI server checks for code changes every 15 minutes and pushes updated version
 of images if needed.
 
-## Docker images
-
-Kapua Docker images are hosted under [Kapua DockerHub account](https://hub.docker.com/r/kapua/). The latest snapshots of images are updated every 15 minutes.
-
-In order to build Kapua Docker images yourself, execute Maven build with `docker` profile enabled:
-
-    mvn clean install -Pdocker
-
-Just like building Kapua from the source code, also add the `console` profile to generate the Web Console docker image:
-
-    mvn clean install -Pdocker,console
-
-If you want to speed up the build process you can ask Maven to ignore `-SNAPSHOT` updates
-force it to use only locally present artifacts with the `dev` profile. You can also skip unit tests to speed things even more.
-
-    mvn clean install -Pdocker,dev -DskipTests
-
-Again, don't forget the `console` profile if the Web Console image is needed:
-
-    mvn clean install -Pdocker,dev,console -DskipTests
-
-### Pushing
+### Pushing docker images
 
 Pushing with default settings:
 

docs/developer-guide/en/running.md

@@ -11,13 +11,14 @@ production setup. {% endhint %}
 Before running Kapua on Docker, you need to
 
 1. Install `docker` and `docker-compose`
-2. Run `mvn -f assembly -Pdocker` once to build containers. Run `mvn -f assembly -Pconsole,docker` if you also need to
-   build the Web Console image.
+2. Make sure that you have built Kapua docker images locally, following the provided building section of this documentation. Alternatively, you can utilize images hosted under the [Kapua DockerHub account](https://hub.docker.com/r/kapua/), for this case we recommend you to follow the "Quick Start Guide" section that can be found in the readme.md file under the root folder.
 
 Now, you can start Kapua by using Docker Compose. To do so, run
 
     kapua/deployment/docker/docker-deploy.sh
 
+Note in case of a deployment of and old version: Assuming that you have built images for a release previous to 2.0.0, and consequently you have done a checkout to the proper tagged commit, keep in mind that the building procedure created a set of docker images tagged as "latest". The "docker-deploy" script pulls images tagged in this way. This implies that the newly built images will be launched. 
+
 After Kapua has been started, you can navigate your browser to http://localhost:8080 and log in using the following
 credentials:
 `kapua-sys` : `kapua-password`
@@ -27,11 +28,6 @@ You can access the API using: http://localhost:8081
 **Note**: If you are using Docker on Windows the hostname will most likely not be `localhost` but the IP address of your
 docker instance.
 
-By default, the `latest` version of images will be used. If you want to run some other version of Kapua, set
-the `IMAGE_VERSION` environment variable, like
-
-    export IMAGE_VERSION=0.2.0
-
 To stop Kapua, run
 
     kapua/deployment/docker/docker-undeploy.sh