You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Eclipse Kapua™](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
19
18
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™ can be deployed in a variety of modes. A practical way for
41
40
Before starting, check that your environment has the following prerequisites:
42
41
43
42
* 64 bit architecture
44
-
* Java VM Version 8
45
-
* Java VM Version 11
46
43
* Docker Version 1.2+
47
-
* Swagger CLI 4+ (Installed via NPM or separately)
48
-
* Node 16+
44
+
* Docker compose V2 for release >= 1.6.12 (present in latest docker desktop versions)
49
45
* Internet Access (needed to download the artifacts)
50
46
51
47
### Demo Setup
@@ -58,21 +54,29 @@ scenarios.
58
54
**Note:** the Docker Hub repository mentioned above is not the official project repository from Eclipse Foundation.
59
55
***
60
56
61
-
Suppose the target is the current snapshot 2.1.0-SNAPSHOT.
57
+
Suppose the target is the released version V (for example, 1.6.7).
62
58
63
59
* Clone Eclipse Kapua™ into a local directory
64
60
* Open an OS shell and move to Kapua project root directory
65
61
* Start Docker runtime
62
+
* Perform a checkout to the related git tag for version V. For the proposed example, the command is:
63
+
64
+
65
+
git checkout 1.6.7
66
+
67
+
* Set the `IMAGE_VERSION` environment variable with a value equal to the target version. For the proposed example:
66
68
67
-
The Kapua repository mentioned above hosts only images of released versions. It is possible to test different versions of Kapua doing a checkout into
68
-
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
69
-
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
70
-
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.
71
-
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
72
-
`IMAGE_VERSION` environment variable with a value equal to the target version. For example, in the case of the 1.6.7
73
69
74
70
export IMAGE_VERSION=1.6.7
75
71
72
+
The repository mentioned above hosts only images of released versions. If your target is a SNAPSHOT version, a local build is required
73
+
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)
74
+
75
+
***
76
+
**A note regarding Docker Compose:** starting from Kapua 1.6.12, the project migrated to Docker Compose V2. This means that,
77
+
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.**
78
+
***
79
+
76
80
* Start Kapua:
77
81
78
82
On Linux/MacOS:
@@ -193,6 +197,10 @@ The credentials for the user kapua-broker are the following:
193
197
**Note**: If you are using Docker on Windows the hostname will most likely not be `localhost` but
194
198
the IP address of your docker instance.
195
199
200
+
### Connecting Kura to Kapua
201
+
202
+
[We provide a quick start guide for the connection of Kura to Kapua](docs/kuraKapuaDocs.md)
203
+
196
204
#### Simulation
197
205
198
206
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:
207
215
*[Running with OpenShift](docs/developer-guide/en/running.md#openshift)
208
216
*[Running with Minishift](docs/developer-guide/en/running.md#minishift)
209
217
210
-
They will provide more advanced deployment scenarios.
218
+
They will provide more advanced deployment scenarios. For example, if you are interested in having debugging/logging capabilities we recommend you to consult them.
Copy file name to clipboardExpand all lines: docs/developer-guide/en/building.md
+29-3
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,32 @@ We use Apache Maven as the build tool of choice.
4
4
5
5
We use `gitbook` to build the documentation.
6
6
7
+
### Requirements
8
+
9
+
Before starting, check that your environment has the following prerequisites:
10
+
11
+
* 64 bit architecture
12
+
* Java VM Version 8
13
+
* Java VM Version 11
14
+
* Docker Version 1.2+
15
+
* Swagger CLI 4+ (Installed via NPM or separately)
16
+
* Node 16+
17
+
* Internet Access (needed to download the artifacts)
18
+
19
+
#### JDK configuration
20
+
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).
21
+
Make sure that the maven runtime is JDK8, follow this https://stackoverflow.com/questions/2503658/specify-jdk-for-maven-to-use if needed.
22
+
23
+
#### Node and Swagger CLI installation
24
+
We propose a command for the installation of these dependencies on Ubuntu, to be run with root privileges:
25
+
26
+
apt install nodejs npm
27
+
npm install -g @apidevtools/swagger-cli
28
+
29
+
#### Docker execution without root privileges
30
+
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.
31
+
To manage docker as a non-root user, we propose this guide for linux: https://docs.docker.com/engine/install/linux-postinstall/
32
+
7
33
## Tests execution
8
34
9
35
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
39
65
40
66
## Docker images building
41
67
42
-
Keep in mind that Kapua Docker images are hosted under [Kapua DockerHub account](https://hub.docker.com/r/kapua/).
68
+
Keep in mind that for release builds Kapua Docker images are hosted under [Kapua DockerHub account](https://hub.docker.com/r/kapua/).
43
69
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:
44
70
45
71
mvn clean install -Pdocker -DskipTests
@@ -57,6 +83,8 @@ Again, don't forget the `console` profile if the Web Console image is needed:
Copy file name to clipboardExpand all lines: docs/developer-guide/en/running.md
+10-13
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,27 @@
1
1
# Running
2
2
3
3
Kapua can be run in a few different ways. See the following chapters for more information about how to start and run
4
-
Kapua.
4
+
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).
5
+
This section is focused on running your custom build.
5
6
6
7
{% hint style='info' %} Most of the following descriptions focus on a developer centric setup and not on a full blown
7
8
production setup. {% endhint %}
8
9
9
10
## Docker containers
10
11
11
-
Before running Kapua on Docker, you need to
12
+
Before running Kapua on Docker, Make sure that you have built Kapua docker images locally, following the provided [building section](building.md).
12
13
13
-
1. Install `docker` and `docker-compose`
14
-
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
15
-
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
16
-
folder.
14
+
### Requirements
15
+
Same as the ones showed in the [building section](building.md) plus
16
+
17
+
* Docker compose V2, starting from Kapua releases >= 1.6.12 (present in latest docker desktop versions)
18
+
19
+
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.
17
20
18
21
Now, you can start Kapua by using Docker Compose. To do so, run
19
22
20
23
kapua/deployment/docker/docker-deploy.sh
21
24
22
-
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
23
-
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
24
-
launched.
25
-
26
25
After Kapua has been started, you can navigate your browser to http://localhost:8080 and log in using the following
27
26
credentials:
28
27
`kapua-sys` : `kapua-password`
@@ -38,9 +37,7 @@ To stop Kapua, run
38
37
39
38
#### Advanced options
40
39
41
-
It's possible to deploy kapua with some advanced options that are exposed in this document:
42
-
43
-
kapua/deployment/docker/README.md
40
+
It's possible to deploy kapua with some advanced options that are exposed [in this document](deployment/docker/README.md)
44
41
45
42
If you are interested in having debugging/logging capabilities we recommend you to consult it.
Copy file name to clipboardExpand all lines: docs/kuraKapuaDocs.md
+4-21
Original file line number
Diff line number
Diff line change
@@ -17,31 +17,14 @@ This is a short introduction to locally connect Kura and Kapua. Although some of
17
17
- Keyboard*
18
18
- Ethernet cable
19
19
- PC (Windows/MAC/Linux)
20
-
* External monitor and keyboard not mandatory, if you can determine Raspberry's IP without them and then establish ssh connection from local PC.
21
-
22
-
## Software Requirements (for PC)
23
-
- 64 bit architecture
24
-
- Java VM Version 8
25
-
- Docker Version 1.2+
26
-
- Internet Access
27
-
20
+
* External monitor and keyboard not mandatory, if you can determine Raspberry's IP without them and then establish ssh connection from local PC.
28
21
29
22
## Downloading and configuring Kapua
30
23
31
-
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.
32
-
33
-
1. Open OS Shell (Terminal) and go to home directory.
34
-
2. Download Kapua project from [Github repository](https://github.com/eclipse/kapua.git) with command `git clone https://github.com/eclipse/kapua.git`
35
-
3. Go to Kapua folder and run command `mvn clean install -DskipTests -Pconsole,docker` which will build the project with the Web Admin console.
36
-
4. After build finishes run Docker deploy script in `deployment/docker`:
37
-
38
-
```
39
-
./docker-deploy.sh
40
-
```
41
-
42
-
The docker images needed will be downloaded from Docker Hub and all the containers will be started.
24
+
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).
25
+
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).
43
26
44
-
You can check if every container is running properly by typing the following command:
27
+
After having launched the deployment script, you can check if every container is running properly by typing the following command:
0 commit comments