Install on Ubuntu

This article guides you through the installation of MaDaM on the Ubuntu operating system.

\uD83D\uDCD8 Instructions

Install Docker Compose

Docker is the preferred container-based deployment platform for MaDaM on Linux systems. Docker Compose enables us to define MaDaM as a multi-container application and makes it very easy to run and update MaDaM. Please follow the installation instructions described at the official Docker website. General information can be found at https://docs.docker.com/engine/install/ , detailed information for specific distributions such as Ubuntu can for example be found at https://docs.docker.com/engine/install/ubuntu/ . Please make sure that Docker-Compose was properly installed by issuing the following command on the terminal

docker-compose –v

The expected output should look similar to

docker-compose version 1.29.2, build 5becea4c

Inspect package structure

Directories and files

The MaDaM package consists of

• a directory containing configuration files for the frontend, backend and KiReporter

• a directory containing mandatory and optional Docker container images.

• a file containing values for environment variables

• the Docker Compose configuration file in YML format

• a bash script for initially loading the Docker images and starting up MaDaM on Docker compose for the first time

Mandatory & optional Docker images

The software package you received, contains all necessary images for running a complete MaDaM system. All images are included, for cases where the installation target server has no internet connection. Some images are mandatory, others do not need to be used, if the respective service already exists within your IT infrastructure.

If you want to use your own instance of ElasticSearch, please refer to section Elasticsearch configuration and adjust files config/MDM-Configuration.json and docker-compose.yml accordingly. Moreover, if you need support for Chinese, Japanese or Korean language, please install the ElasticSearch plugin analysis-icu with command

elasticsearch/bin/elasticsearch-plugin install analysis-icu

If you want to use your own instance of a database server, please refer to section Database configuration and adjust files config/MDM-Configuration.json and docker-compose.yml accordingly. Please note, that only PostgreSQL and MySQL are supported and tested database systems. If you want to use a database system of another vendor, please contact Kistler for a custom solution.

Docker Compose configuration file

Docker Compose uses a file called docker-compose.yml as configuration file. It contains settings for each MaDaM service, such as used volumes for persistent data storage and environment variables. For adjusting MaDaM to your IT landscape, almost only the environment variables in this file need to be changed. Depending on your needs, you might also want to change the password for the PostgreSQL container or remove it entirely, if you want to use a different database server. In most of the cases you will need to change the Java heap memory settings of the ElasticSearch container using a line like

"ES_JAVA_OPTS=-Xms16G -Xmx16G"

in section environment.

Environment variables file

The file called .env is used for quick and clear access to a list of configuration parameters such as host names and network ports. The contained values will be utilized in docker-compose.yml on start-up. This file is optional – the contained configuration parameters can alternatively be directly entered within the section environment within docker-compose.yml.

Create installation directory

We recommend using directory /opt/madam for installation of the application binaries. Create that directory with

mkdir /opt/madam

and copy all binaries and configuration fies to this location.

Configure mandatory settings

Some mandatory configuration options must be set with each initial installation.

Server host name

The fully qualified host name or IP address of the server running the MaDaM system is specific to the environment in which the system is deployed. Hence it must be configured in file .env.

Example:

HOST_FQDN=192.168.xxx.xx

Backend license server

The backend service needs to check against the license server and hence needs the host name or IP address of that license server. This value needs to be configured in file config/MDM-Configuration.json

"license": {
 "licenseServer": "192.168.xxx.xx"
}

KiReporter license server

The KiReporter needs to check against the license server and hence needs the host name or IP address of that license server. This value needs to be configured in file config/Configuration.xml

<WebserviceLicenseServer>
  <String>192.168.xxx.xx</String>
</WebserviceLicenseServer>
<ClientLicenseServer>
  <String>192.168.xxx.xx</String>
</ClientLicenseServer>

Database credentials

If the PostgreSQL docker container should be used with MaDaM, at least the database password should be changed. This can be done in file docker-compose.yml

database:
 image: postgres:10.4
 restart: always
 environment:
 POSTGRES_USER: madam
 POSTGRES_PASSWORD: changeme
 POSTGRES_DB: madam
 volumes:
 - dbdata:/var/lib/postgresql/data

In addition to this, the password needs to be changed in file config/MDM-Configuration.json

"database": {
 "hibernate.connection.password":"changeme"
}

Persistent data directories

By default, the file docker-compose.yml will mount so-called named volumes like

volumes: 
  - filestorage:/filestorage/madam-data

The volumes will be backed and managed by the Docker installation. Please refer to https://docs.docker.com/storage/volumes/ for more details on how to manage and backup volumes using docker. As an alternative to volumes, it is possible to mount directories of the host file system (so-called bind-mounts) in docker-compose.yml. Please refer to https://docs.docker.com/storage/bind-mounts/ for more details. The following table lists all volumes with their meanings as well as an alternative example bind-mount:

Start MaDaM & services

To run MaDaM after the minimum configuration is done, please execute the shell script named install-madam.sh (or install-madam-demo.sh for the demo version) from within the MaDaM installation directory. Please make sure, that the shell script is executable with command:

ls -l install-madam.sh

The resulting output should look like:

-rwxr-xr-x 1 User 1049089 690 Jun 7 11:40 install-madam.sh

If the script is not executable, please use the following command to set the executable flags:

chmod +x install-madam.sh

After this, please execute the script using

./install-madam.sh

The script will perform the following virtual memory setting for Elasticsearch

sysctl -w vm.max_map_count=262144

then loads the provided Docker images, creates a directory for the logs within the current directory and finally starts all containers using Docker Compose.

Once all MaDaM containers are running and after waiting for about one and a half minute after the first boot, please navigate to the web UI using http://192.168.xxx.xx:8080 (please replace the IP by the one you configured for HOST_FQDN in file .env and use https instead, if configured).

\uD83D\uDCCB Related articles

• Page:
  Update on Ubuntu
• Page:
  Install on Ubuntu