KNOWAGE Enterprise Installation using Docker

In this chapter, we will describe how to install the Enterprise version of KNOWAGE using Docker. Please note that access to the repository is granted through authorization.

Prerequisites

Some preliminary operations are required:

Installation on the host machine of Docker/Podman.

Internet access from the host machine is required at the time of installation (for OS updates and Knowage image updates).

If internet access is not available, it will be necessary to manually transfer to the host machine both the “knowage-ee-server-docker” folders mentioned in paragraph ‘Repository cloning’ and manually copy the Knowage images.

Repository cloning

To install Knowage EE via Docker, you need to clone the GitLab repository:

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

access the project directory:

shell command
 cd knowage-ee-server-docker

N.B. in the absence of an internet connection, the following files and folders must be copied to the host machine in the knowage-ee-server-docker folder

  1. docker-compose.yaml

  2. .env

  3. the “resources” folder

  4. the “conf” folder

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.

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

  • 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)

DB password encryption

To encrypt the database password you need:

  1. download the tomcat-password-encryption.jar jar in the “knowage-enterprise” directory from https://github.com/KnowageLabs/Knowage-Server-ee

  2. run the following command (with java 17 or later):

Java command
 java -cp tomcat-password-encryption.jar -Dsymmetric_encryption_key=KEY_SECRET it.eng.knowage.enterprise.tomcatpasswordencryption.helper.EncryptOnce DB_CLEAR_PASSWORD

where KEY_SECRET corresponds to the value indicated in the SENSIBLE_DATA_ENCRYPTION_SECRET environment variable

where DB_CLEAR_PASSWORD is the plaintext password of the database

  1. replace the values ​​obtained in correspondence with the DB_PASS_ENCRYPTED and CACHE_DB_PASS_ENCRYPTED environment variables respectively

Installation of Database Schemas

It is necessary to manually install the knowage and knowage_cache schemes on the customer database, executing the related DDLs.

Make sure to update the parameters in the .env file with the correct data for DB access.

Check the connectivity between the host machine where Knowage will be installed and the DB.

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:

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

Example of Resource in extGlobalResources:

 1 <Resource
 2     auth="Container"
 3     driverClassName="com.mysql.jdbc.Driver"
 4     logAbandoned="true"
 5     maxTotal="20"
 6     maxIdle="4"
 7     maxWait="300"
 8     minEvictableIdleTimeMillis="60000"
 9     name="jdbc/foodmart"
10     password="foodmart"
11     removeAbandoned="true"
12     removeAbandonedTimeout="3600"
13     testOnReturn="true"
14     testWhileIdle="true"
15     timeBetweenEvictionRunsMillis="10000"
16     type="javax.sql.DataSource"
17     url="jdbc:mysql://foodmart:3306/foodmart"
18     username="foodmart"/>

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

Note on paths and mounted volumes

The paths and directories specified in the docker-compose.yml file volumes (e.g. ./resources, ./conf/server.xml.d, etc.) must be adapted according to the structure and needs of the host machine on which Knowage is running.

Make sure the directories exist and contain the necessary files before starting the containers. Otherwise, the service may not start correctly or work as expected.

On the directories change the permissions with the following commands:

Example:

shell command
 chown -R knowage:knowage /portal_data/knowage_*

 chmod -R 750 /portal_data/knowage_*

 Create the following file with the command:

 vim ~/.config/containers/containers.conf and write
shell command
   [containers]

   userns="keep-id"

Configuring additional hosts

You can add the extra_hosts parameter within the service definition in the docker-compose.yml file to map custom hostnames to specific IP addresses.

This can be useful, for example, to resolve internal DNS names or to facilitate communication with external services not managed by Docker.

Example:

docker-compose.yaml fragment
 extra_hosts:

   - "hostname:192.168.1.100"

Container network setup

In the docker-compose.yml file, the network_mode: “host” parameter is used to make containers share the host’s network.

However, this configuration is not always the most suitable, especially in multi-container or production environments, where it is preferable to isolate services.

Alternatively, you can define a dedicated Docker network and assign it to containers, improving the security and flexibility of communication between services.

Caution with network_mode parameter: “host” cannot install the Hazelcast container for clustering

Dedicated network example:

docker-compose.yaml fragment
 networks:
   knowage_net

 services:
   know-how:
     networks:
       - knowage_net
   hazelcast:
     networks:
       - knowage_net

Launching Knowage Services

Go to the knowage-ee-server-docker directory and authenticate in the private repository:

docker command
 podman login knowage.azurecr.io

After login, start the services:

docker command
 podman composed up –d

Components Installed

  • Knowage Tomcat with all packages

  • Hazelcast for clustering

  • KnowagePython for integration with Python

Access the web interface: http://localhost:8080/knowage-vue/