Kapua on Docker
January 12, 2024 ยท View on GitHub
To learn more on how to run Kapua using Docker, please consult developer manual.
The most recent version of the documentation can be viewed online at:
- http://download.eclipse.org/kapua/docs/develop/user-manual/en/
- http://download.eclipse.org/kapua/docs/develop/developer-guide/en/
How to run Kapua on Docker.
You are required to have Docker installed and running.
It is advisable to give to Docker at least 6GB of ram and 2 CPUs.
Running
Just simply run:
./unix/docker-deploy.sh
PowerShell scripts are also available for Windows OS:
.\win\docker-deploy.ps1
Accessing components
After deployment and startup of containers, they can be accessed at the following endpoints
| Application/Service | Endpoint | User | Password | Others |
|---|---|---|---|---|
| H2 SQL | localhost:3306 | kapua | kapua | Schema name: kapuadb |
| Elasticsearch | localhost:9200 | |||
| Message Broker | localhost:1883 | kapua-broker | kapua-password | |
| Admin WEB Console | localhost:8080 | kapua-sys | kapua-password | |
| REST API endpoint | localhost:8081 | kapua-sys | kapua-password | API KEY: 12345678kapua-password |
Checking
You can check Docker containers logs to check that everything has started and is running properly, by running:
./unix/docker-logs.sh
Powershell:
.\win\docker-logs.ps1
You can also start check logs with the ./docker-deploy.sh script by providing the --logs option:
./unix/docker-deploy.sh --logs
Powershell
.\win\docker-deploy.ps1 --logs
Tear down
To stop and remove all containers, run:
./unix/docker-undeploy.sh
Powershell:
.\win\docker-undeploy.ps1
Single Sign On (OpenID Connect)
This section needs to be updated
To enable Single Sign On (SSO), please refer to deployment/docker/unix/sso/README.md. For more details about the SSO
deployment, please check the docs/developer-guide/en/sso.md SSO developer guide.
Advanced options
Setting the Kapua version
Other than the default deployment it is possible to run other versions of Kapua.
By default, the latest version of Kapua will be brought up. You can change the version of Kapua by exporting the
environment variable IMAGE_VERSION. Please also remember to checkout the related git tag first.
Example:
git checkout 1.0.0-M5
export IMAGE_VERSION=1.0.0-M5
./docker-deploy.sh
Enabling development mode
Development mode deploys some development components to help development and debugging.
To enable it, provide the --dev option.
Example:
./docker-deploy.sh --dev
Following ports/components will be available:
| Application/Service | Endpoint |
|---|---|
| H2 Web Admin console | localhost:8181 |
| Elasticsearch Browser | localhost:55000 |
Notes
H2 Web Admin Console
The parameters to connect to H2 DB instance are the following
| Parameter | Value |
|---|---|
| Saved Settings | Generic H2 (Server) |
| Driver Class | org.h2.Driver |
| Driver Class | org.h2.Driver |
| JDBC URL | jdbc:h2:tcp://localhost:3306/kapuadb |
| User Name | kapua |
| Password | kapua |
It is to be noted that as an alternative of the web console you can, of course, use whatever database tool you like, for example DBeaver https://dbeaver.io/
Elasticsearch Browser
Deployed component is already configured to connect to Elasticsearch instance.
Enabling remote JVM debug mode
Containers can also be remotely debugged. To enable it, provide the --debug option.
Example:
./docker-deploy.sh --debug
Following ports will be opened
| Application/Service | Remote JVM debug endpoint |
|---|---|
| Message Broker | localhost:5005 |
| Consumer Lifecycle | localhost:8002 |
| Consumer Telemetry | localhost:8001 |
| Service Authentication | localhost:8004 |
| Admin WEB Console | localhost:5007 |
| REST API endpoint | localhost:5006 |
| Job Engine | localhost:5008 |
Enabling JMX mode
Containers can be accessed via JMX. For example, you can use it to analyse the JVM using jConsole.
To enable it, provide the --jmx option.
Example:
./docker-deploy.sh --jmx
Following ports will be opened
| Application/Service | Remote JVM debug endpoint |
|---|---|
| Message Broker | localhost:9875 |
| Consumer Lifecycle | localhost:9876 |
| Consumer Telemetry | localhost:9877 |
| Service Authentication | localhost:9880 |
| REST API endpoint | localhost:9881 |
| Admin WEB Console | localhost:9882 |
| Job Engine | localhost:9883 |
Building containers from scratch
If you want to build containers from the code, you'll need to build the whole Kapua Project.
From the project root directory, run:
mvn clean install -Pdocker
To build also the Admin Web Console container, which is excluded by default, add the console profile:
mvn clean install -Pconsole,docker
After the build has completed follow the steps from the Running section.
Enabling Single Sing On (SSO)
Kapua can be deployed with an SSO provider. To enable it, provide the --sso option.
Example:
./docker-deploy.sh --sso
By adding this option Kapua will be deployed with an instance of Keycloak SSO provider.
The Keycloack instance can be accessed at the following endpoints:
| Application/Service | Endpoint | User | Password | Notes |
|---|---|---|---|---|
| Keycloak Console | localhost:9090 | admin | admin |
This option is not available on Windows OS at the moment.
Enabling SSL
Kapua can be deployed with an SSL enabled. To enable it, provide the --ssl option.
SSL will be enabled for the following services
| Application/Service | Endpoint |
|---|---|
| Message Broker | To be implemented |
| Admin WEB Console | localhost:8443 |
| REST API endpoint | localhost:8444 |
The --ssl options configures a self-signed keypair created on the fly.
If you want to provide your certificates, follow the instruction below.
Providing certificates and private key
To use an existing certificate, a private key and a CA you can set the following environment variables:
- KAPUA_CRT: The certificate to use
- KAPUA_CA: Optional - The CA chain that validates the certificate
- KAPUA_KEY The private key for the certificate
- KAPUA_KEY_PASSWORD Optional - The password for the private key
All the values should be exported as inline values. e.g.:
export KAPUA_CA=$(cat /path/to/myCA.pem)
export KAPUA_CRT=$(cat /path/to/certificate.crt)
export KAPUA_KEY=$(cat /path/to/private.key)
export KAPUA_KEY_PASSWORD=private_key_password
Please notice that these variables must be exported from the shell as shown above. Declare them in a env file or
setting them in the docker-compose file does not work because the command substitution does not happen in these cases.
Providing a Keystore
Otherwise, two environment variables can be used to provide an already existing keystore and its password:
- KAPUA_KEYSTORE: The base64 encoded keystore
- KAPUA_KEYSTORE_PASSWORD: The password for the keystore
Again, All the values should be exported as inline values. e.g.:
export KAPUA_KEYSTORE=$(base64 /path/to/keystore.pkcs)
export KAPUA_KEYSTORE_PASSWORD=keystore_password
Providing custom logging level
The info logging level is used as default root level in container logs. To provide a different logging level you can
set the following environment variable:
- LOGBACK_LOG_LEVEL: The logging level value
Allowed logging level values are: trace, debug, info, warn, error, all or off. e.g.:
export LOGBACK_LOG_LEVEL=debug