KNOWAGE Community Installation using Docker

In this guide, you will find instructions on how to install KNOWAGE Community Edition using Docker. You can install Knowage by connecting it to an existing external database, or by loading the Docker image of the MySQL database as well.

Repository cloning

First f all, to install Knowage CE via Docker, you need to clone the GitHub repository:

git command

     git clone https://github.com/KnowageLabs/Knowage-Server-Docker.git

Preparation of the Environment

Access the project directory:

shell command

   cd Knowage-Server-Docker

Configuration of Environment Variables

Knowage requires several variables to be configured to launch correctly.

These can be defined in the .env file present in the project directory. KNOWAGE need to use 2 DB schema, one for the metadata and una for the temporary cache.

For an initial demo installation using the included database, you can keep the database configuration settings as default. You must change them if you are using an existing external database — see Using External Databases section.

Data base parameters:

DB_HOST: database host
DB_PORT: database port
DB_DB: database name
DB_USER: database user
DB_PASS: user password
CACHE_DB_HOST: cache database host
CACHE_DB_PORT: cache database port
CACHE_DB_DB: name of the cache database
CACHE_DB_USER: cache database user
CACHE_DB_PASS: cache user password
HMAC_KEY: HMAC key to configure in Tomcat, it is important to configure it carefully, avoiding the use of trivial or predictable strings, as this setup is used to generate the token.
PASSWORD_ENCRYPTION_SECRET: key for password encryption. Key used to securely store user passwords
SENSIBLE_DATA_ENCRYPTION_SECRET: key for encrypting sensitive data. It is used for data decryption functionalities.

Parameters in the docker-compose.yml file

DB_DO_INITIALIZATION: Defaults to true; Set to false to avoid initializing the database. This is useful when using an already initialized external database, see Using External Databases section.
HAZELCAST_HOSTS: Comma-separated Hazelcast hosts (e.g., “host1,host2,host3”)
HAZELCAST_PORT: Hazelcast port (e.g., “5701”)
PUBLIC_ADDRESS: IP or hostname visible from the outside (e.g. http://$PUBLIC_ADDRESS:8080/knowage)
DB_TYPE: database type (default: MYSQL; options: MYSQL, MARIADB, ORACLE, POSTGRES)
CACHE_DB_TYPE: database type (default: MYSQL; options: MYSQL, MARIADB, ORACLE, POSTGRES)

Complete Installation

To install all Knowage components without demo content, run:

docker command

   podman compose up -d

Instead, if you want to install the demo version with preconfigured reports, run:

docker command

   podman compose -f docker-compose-demo.yml up -d

Components Installed

Knowage Tomcat with all packages
Hazelcast
KnowagePython for Python integration
KnowageDB (metadata)
KnowageCache (cache)

Access the web interface: http://localhost:18080/knowage

Changing the Access Port

To change the port on which Knowage is exposed, edit the **docker-compose.yml file in the knowage service section.

docker command

   version: "3.8"
      services:
      knowage:
         image: knowagelabs/knowage-server-docker:9.0
         hostname: knowage
      depends_on:
         - knowagedb
         - knowagecache
         - hazelcast
      ports:
         - "18080:8080"
      networks:
         - main

Using External Databases

It may be useful to use an existing external database instead of the one included in the standard distribution. In that case, you should:

Remove the knowagedb service from docker-compose.yml.

docker compose fragment

     knowagedb:
      image: mariadb:10.3
         environment:
            - MYSQL_USER=$DB_USER
            - MYSQL_PASSWORD=$DB_PASS
            - MYSQL_DATABASE=$DB_DB
            - MYSQL_RANDOM_ROOT_PASSWORD=yes
         networks:
            - main
      volumes:
         - "db:/var/lib/mysql"

Install the Knowage schema on your database via DDL, you can find here the DDL.
Update the parameters in the .env file.
Set DB_DO_INITIALIZATION : false.

The same applies to using an external database for the cache (knowagecache).

Adding JNDI Resources

To add new JNDI resources, edit the following files:

conf/context.xml.d/extContext
conf/server.xml.d/extGlobalResources

Example of ResourceLink in extContext:

   <ResourceLink global="jdbc/foodmart" name="jdbc/foodmart" type="javax.sql.DataSource" />

Example of Resource in extGlobalResources:

   <Resource
 auth="Container"
 driverClassName="<DRIVER JDBC>"
 logAbandoned="true"
 maxTotal="20"
 maxIdle="4"
 maxWait="300"
 minEvictableIdleTimeMillis="60000"
 name="jdbc/<JNDI NAME>"
 password="<PASSWORD>"
 removeAbandoned="true"
 removeAbandonedTimeout="3600"
 testOnReturn="true"
 testWhileIdle="true"
 timeBetweenEvictionRunsMillis="10000"
 type="javax.sql.DataSource"
 url="jdbc:mysql://<IP ADRESS>:<PORT>/<DB NAME>"
 username="<USERNAME>"/>

Mounting volumes in docker-compose.yml in the volumes section of the knowage service:

./conf/confServerFoodmart:/home/knowage/apache-tomcat/conf/server.xml.d
./conf/context.xml.d:/home/knowage/apache-tomcat/conf/context.xml.d

How upgrade KNOWAGE version

If you want to upgrade the KNOWAGE packages to the last patch version released ( eg. from 9.0.0 to 9.0.1) you have to:

docker command

 podman compose down
 podman rmi <IMAGE ID>
 podman compose up -d