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

…r instructions

Signed-off-by: Alberto Codutti <alberto.codutti@eurotech.com>

README.md

@@ -57,6 +57,16 @@ Suppose the target is the current snapshot 1.6.8-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:
@@ -73,12 +83,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,26 +4,30 @@ 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.
+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
 
-You can run the Kapua full build issuing the command:
+## Docker images building
 
-    mvn clean install
+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:
 
-Don't forget to also add the `console` Maven profile if you are interested in building the Web Console as well:
+    mvn clean install -Pdocker -DskipTests
 
-    mvn clean install -Pconsole
+Add the `console` profile to generate also the Web Console docker image:
 
-If you only want to run Kapua locally for testing you can speed up the build
-by using:
+    mvn clean install -Pdocker,console -DskipTests
 
-    mvn clean install -Pdev -DskipTests=true
+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.
 
-Again, add the `console` profile as well if needed:
+    mvn clean install -Pdocker,dev -DskipTests
 
-    mvn clean install -Pdev,console -DskipTests=true
+Again, don't forget the `console` profile if the Web Console image is needed:
+
+    mvn clean install -Pdocker,dev,console -DskipTests
 
 ## Security Scan
 
@@ -106,7 +110,7 @@ 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

@@ -13,12 +13,14 @@ setup and not on a full blown production setup.
 Before running Kapua on Docker, you need to
 
 1. Install `docker` and `docker-compose`
-1. 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 1.7.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,10 +29,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