Merge pull request #4163 from Agnul97/fix-documentation_review

✨ [Docs] Various documentation improvements

README.md

@@ -13,7 +13,6 @@
 ![Gitter](https://img.shields.io/gitter/room/eclipse/kapua?label=Chat&logo=gitter)
 
 ![GitHub Actions CI](https://img.shields.io/github/actions/workflow/status/eclipse/kapua/kapua-ci.yaml) <br/>
-![Jenkins](https://img.shields.io/jenkins/build?jobUrl=https:%2F%2Fci.eclipse.org%2Fkapua%2Fjob%2Fdevelop-build&label=Jenkins%20Build&logo=jenkins) <br/>
 
 [Eclipse Kapua&trade;](http://eclipse.org/kapua) is a modular platform providing the services required to manage IoT gateways and smart edge devices. Kapua provides a core integration framework and an
 initial set of core IoT services including a device registry, device management services, messaging services, data management, and application enablement.
@@ -41,11 +40,8 @@ Eclipse Kapua&trade; can be deployed in a variety of modes. A practical way for
 Before starting, check that your environment has the following prerequisites:
 
 * 64 bit architecture
-* Java VM Version 8
-* Java VM Version 11
 * Docker Version 1.2+
-* Swagger CLI 4+ (Installed via NPM or separately)
-* Node 16+ 
+  * Docker compose V2 for release >= 1.6.12 (present in latest docker desktop versions)
 * Internet Access (needed to download the artifacts)
 
 ### Demo Setup
@@ -58,21 +54,29 @@ 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.1.0-SNAPSHOT.
+Suppose the target is the released version V (for example, 1.6.7).
 
 * Clone Eclipse Kapua&trade; into a local directory
 * Open an OS shell and move to Kapua project root directory
 * Start Docker runtime
+* Perform a checkout to the related git tag for version V. For the proposed example, the command is:
+
+
+    git checkout 1.6.7
+
+* Set the `IMAGE_VERSION` environment variable with a value equal to the target version. For the proposed example:
 
-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.1.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
 
+The repository mentioned above hosts only images of released versions. If your target is a SNAPSHOT version, a local build is required
+in order to create the docker images and proceed to the next step. [Here you can found instructions for building](docs/developer-guide/en/building.md)
+
+***
+**A note regarding Docker Compose:** starting from Kapua 1.6.12, the project migrated to Docker Compose V2. This means that,
+depending on your terget version V, your Docker Desktop version should be aligned accordingly in order to smoothly deploy the application. If you are trying to deploy a version BEFORE 1.6.12, make sure to have a Docker Desktop version released before july 2023. Otherwise, the latest should be fine.**
+***
+
 * Start Kapua:
 
 On Linux/MacOS:
@@ -193,6 +197,10 @@ The credentials for the user kapua-broker are the following:
 **Note**: If you are using Docker on Windows the hostname will most likely not be `localhost` but
 the IP address of your docker instance.
 
+### Connecting Kura to Kapua
+
+[We provide a quick start guide for the connection of Kura to Kapua](docs/kuraKapuaDocs.md)
+
 #### Simulation
 
 Kapua comes with a framework that you can use to simulate Kura gateways. It can be used to test your Kapua deployments easily. See [Simulator documentation](docs/user-manual/en/simulator.md) for more
@@ -207,12 +215,12 @@ guides:
 * [Running with OpenShift](docs/developer-guide/en/running.md#openshift)
 * [Running with Minishift](docs/developer-guide/en/running.md#minishift)
 
-They will provide more advanced deployment scenarios.
+They will provide more advanced deployment scenarios. For example, if you are interested in having debugging/logging capabilities we recommend you to consult them.
 
 ### User & Developer guides
 
-* [User Manual](http://download.eclipse.org/kapua/docs/develop/user-manual/en)
-* [Developer Guide](http://download.eclipse.org/kapua/docs/develop/developer-guide/en)
+* [User Manual](docs/user-manual/en/README.md)
+* [Developer Guide](docs/developer-guide/en/README.md)
 
 ### Contributing
 

build-tools/src/main/toolchains/README.md

@@ -14,14 +14,24 @@ those directly or create a new toolchain file which works for you.
 This file is for Fedora/RHEL/CentOS based distributions. In order to install required JDKs issue
 the following commands with root privileges:
 
-    yum install java-1.6.0-openjdk-devel java-1.7.0-openjdk-devel java-1.8.0-openjdk-devel
+    yum install java-1.8.0-openjdk-devel java-11-openjdk-devel
 
 Or (when using `dnf` instead of `yum`):
 
-    dnf install java-1.6.0-openjdk-devel java-1.7.0-openjdk-devel java-1.8.0-openjdk-devel
+    dnf install java-1.8.0-openjdk-devel java-11-openjdk-devel
 
 Open the file, modify the jdk path in order to match your machine configuration, and then copy this file to `~/.m2/toolchains.xml` to use it.
 
+## Ubuntu
+
+- `ubuntu.xml`
+
+This file is for Ubuntu based distributions. In order to install required JDKs issue
+the following commands with root privileges:
+
+    apt install openjdk-11-jdk
+    apt install openjdk-8-jdk
+
 ## MacOS
 
 - `macos.xml`

build-tools/src/main/toolchains/ubuntu.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF8"?>
+<!--
+    Copyright (c) 2022 Eurotech and/or its affiliates and others
+
+    This program and the accompanying materials are made
+    available under the terms of the Eclipse Public License 2.0
+    which is available at https://www.eclipse.org/legal/epl-2.0/
+
+    SPDX-License-Identifier: EPL-2.0
+
+    Contributors:
+        Eurotech - initial API and implementation
+ -->
+<toolchains>
+    <!-- JDK toolchains -->
+    <toolchain>
+        <type>jdk</type>
+        <provides>
+            <version>8</version>
+        </provides>
+        <configuration>
+            <jdkHome>/usr/lib/jvm/java-8-openjdk-arm64</jdkHome>
+        </configuration>
+    </toolchain>
+
+    <toolchain>
+        <type>jdk</type>
+        <provides>
+            <version>11</version>
+        </provides>
+        <configuration>
+            <jdkHome>/usr/lib/jvm/java-11-openjdk-arm64</jdkHome>
+        </configuration>
+    </toolchain>
+</toolchains>

docs/developer-guide/en/building.md

@@ -4,6 +4,32 @@ We use Apache Maven as the build tool of choice.
 
 We use `gitbook` to build the documentation.
 
+### Requirements
+
+Before starting, check that your environment has the following prerequisites:
+
+* 64 bit architecture
+* Java VM Version 8
+* Java VM Version 11
+* Docker Version 1.2+
+* Swagger CLI 4+ (Installed via NPM or separately)
+* Node 16+
+* Internet Access (needed to download the artifacts)
+
+#### JDK configuration
+The project has some modules that builds with JDK 8 and some with JDK11. To enable this, you first must configure the toolchain, as explained [in this document](../../../build-tools/src/main/toolchains/README.md).
+Make sure that the maven runtime is JDK8, follow this https://stackoverflow.com/questions/2503658/specify-jdk-for-maven-to-use if needed.
+
+#### Node and Swagger CLI installation
+We propose a command for the installation of these dependencies on Ubuntu, to be run with root privileges:
+
+     apt install nodejs npm
+     npm install -g @apidevtools/swagger-cli
+
+#### Docker execution without root privileges
+In the phase of docker images building, a maven plugin invokes the docker daemon to do so. If, in your environment, you are not able to run docker without root privileges, you will need to build the project with these privileges.
+To manage docker as a non-root user, we propose this guide for linux: https://docs.docker.com/engine/install/linux-postinstall/
+
 ## Tests execution
 
 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
@@ -39,7 +65,7 @@ Launch it in order to build Kapua executing all the tests. Integration tests are
 
 ## Docker images building
 
-Keep in mind that Kapua Docker images are hosted under [Kapua DockerHub account](https://hub.docker.com/r/kapua/). 
+Keep in mind that for release builds 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
@@ -57,6 +83,8 @@ Again, don't forget the `console` profile if the Web Console image is needed:
 
     mvn clean install -Pdocker,dev,console -DskipTests
 
+Having built your images, you can now run them following the [running section](running.md).
+
 ## Security Scan
 
 You can perform the CVE scan of the project by running with the following command:
@@ -109,7 +137,6 @@ To build documentation, run `gitbook build` from either `docs/developer-guide/en
 Kapua is running CI builds in the following public environments:
 
 - GitHub Actions  ![GitHub Actions CI](https://img.shields.io/github/workflow/status/eclipse/kapua/kapua-continuous-integration?label=GitHub%20Action%20CI&logo=GitHub)
-- Eclipse Hudson  ![Hudson](https://img.shields.io/jenkins/build?jobUrl=https:%2F%2Fci.eclipse.org%2Fkapua%2Fjob%2Fdevelop-build&label=Jenkins%20Build)
 
 Please be sure that both environments are "green" (i.e. all tests pass) after you commit any changes into `develop` branch.
 
@@ -135,5 +162,4 @@ Don't forget to add the `console` Maven profile to the console above if you're i
 
 By default Kapua applies the following tags to the published images:
 - `latest`
-- daily timestamp in format `YYYY-MM-DD`
 - current project version (for example `0.0.1` or `0.1.2-SNAPSHOT`)

docs/developer-guide/en/running.md

@@ -1,28 +1,27 @@
 # Running
 
 Kapua can be run in a few different ways. See the following chapters for more information about how to start and run
-Kapua.
+Kapua. Keep in mind that if you want to deploy a released version, not building anything, you can follow the [Kapua quick start guide](https://github.com/eclipse/kapua/blob/develop/README.md).
+This section is focused on running your custom build.
 
 {% hint style='info' %} Most of the following descriptions focus on a developer centric setup and not on a full blown
 production setup. {% endhint %}
 
 ## Docker containers
 
-Before running Kapua on Docker, you need to
+Before running Kapua on Docker, Make sure that you have built Kapua docker images locally, following the provided [building section](building.md).
 
-1. Install `docker` and `docker-compose`
-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.
+### Requirements
+Same as the ones showed in the [building section](building.md) plus
+
+* Docker compose V2, starting from Kapua releases >= 1.6.12 (present in latest docker desktop versions)
+
+If you previously set the IMAGE_VERSION environment variable to a released version, please now unset it. In this way, latest built Kapua docker images will be deployed.
 
 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`
@@ -38,9 +37,7 @@ To stop Kapua, run
 
 #### Advanced options
 
-It's possible to deploy kapua with some advanced options that are exposed in this document:
-
-kapua/deployment/docker/README.md
+It's possible to deploy kapua with some advanced options that are exposed [in this document](deployment/docker/README.md)
 
 If you are interested in having debugging/logging capabilities we recommend you to consult it.
 

docs/kuraKapuaDocs.md

@@ -17,31 +17,14 @@ This is a short introduction to locally connect Kura and Kapua. Although some of
    - Keyboard*
    - Ethernet cable
  - PC (Windows/MAC/Linux)
- * External monitor and keyboard not mandatory, if you can determine Raspberry's IP without them and then establish ssh connection from local PC. 
-
- ## Software Requirements (for PC)
-  - 64 bit architecture 
-  - Java VM Version 8 
-  - Docker Version 1.2+
-  - Internet Access
-
+ * External monitor and keyboard not mandatory, if you can determine Raspberry's IP without them and then establish ssh connection from local PC.
 
 ## Downloading and configuring Kapua
 
-This part of the tutorial consists of several pieces. First you need to download Java VM, Docker and Kapua. You can get Java [here](https://java.com/en/download/) and Docker [here](https://docs.docker.com/engine/installation/#supported-platforms). After that follow steps bellow for downloading and building Kapua.
-
-1. Open OS Shell (Terminal) and go to home directory.
-2. Download Kapua project from [Github repository](https://github.com/eclipse/kapua.git) with command `git clone https://github.com/eclipse/kapua.git`
-3. Go to Kapua folder and run command `mvn clean install -DskipTests -Pconsole,docker` which will build the project with the Web Admin console.
-4. After build finishes run Docker deploy script in `deployment/docker`:
-
-```
-./docker-deploy.sh
-```
-
-The docker images needed will be downloaded from Docker Hub and all the containers will be started.
+Keep in mind that if you want to deploy a released version, not building anything, you can follow the [Kapua quick start guide](https://github.com/eclipse/kapua/blob/develop/README.md).
+If, otherwise, you want to deploy your build, we recommend [this reading](developer-guide/en/building.md) and then [this reading](developer-guide/en/running.md).
 
-You can check if every container is running properly by typing the following command:
+After having launched the deployment script, you can check if every container is running properly by typing the following command:
 
   docker ps -as