Official configurations for the docker setup of TOLERANT Match

The configurations for each released version can be found under tags

Package Content

+-- config
|   +-- grafana
|   |   +-- dashboards
|   |   |   +-- cluster
|   |   |   |   +-- dashboard.yml            # a configuration file for grafana
|   |   |   |   +-- main_dashboard.json      # an example dashboard to display metrics data
|   |   |   +-- service
|   |   |   |   +-- dashboard.yml            # a configuration file for grafana
|   |   |   |   +-- main_dashboard.json      # an example dashboard to display metrics data
|   |   +-- datasources
|   |       +-- datasource.yml               # an example datasource's configuration to request the data from
|   +-- keycloak
|   |   +-- import
|   |       +-- tolerant-realm.json          # an example keycloak configuration for TOLERANT
|   +-- kubernetes
|   |   +-- match-cluster.yml                # an example kubernetes setup for match a cluster
|   |   +-- match-cluster-config.yml         # example configurations for the kubernetes match cluster example
|   |   +-- match-env.yml                    # environment variables for the kubernetes match cluster example
|   |   +-- match-cxpose.yml                 # an example proxy configuration for the kubernetes match cluster example
|   +-- nginx
|   |   +-- ssl
|   |   |   +-- certs                        # a folder to store the self-assigned certificate for the nginx 
|   |   |   +-- private                      # a folder to store the private key for the nginx
|   |   +-- default.conf.template            # an example of nginx configuration for forwarding request to TOLERANT Match
|   |   +-- default.no.gui.conf.template     # an example of nginx configuration without gui for forwarding request to TOLERANT Match
|   |   +-- default_cluster.conf.template    # an example of nginx configuration for forwarding request to the TOLERANT Match cluster example
|   |   +-- httppaswd                        # an example password file in case of basic auth
|   |   +-- locations
|   |   |   +-- keycloak.loc.template        # an example of nginx location configuration for forwarding request to the Keycloak example
|   |   +-- ssl.conf.template                # an example of nginx configuration for forwarding https request to TOLERANT Match
|   |   +-- ssl.no.gui.conf.template         # an example of nginx configuration without gui for forwarding https request to TOLERANT Match
|   +-- node1
|   |   +-- matchserviceconfig.xml           # an example configuration for cluster node 1       
|   +-- node2
|   |   +-- matchserviceconfig.xml           # an example configuration for cluster node 2
|   +-- openssl
|   |   +-- docker-entrypoint.sh             # an entrypoint for the openssl image to create ssl certificates 
|   |   +-- Dockerfile                       # a dockerfile to build the openssl image on startup
|   +-- prometheus
|       +-- prometheus.yml                   # a prometheus configuration for collecting metrics data
|       +-- prometheus-cluster.yml           # a prometheus configuration for collecting metrics data for match the cluster example
+-- .env                                     # a file containing variables for the compose files
+-- compose.yml                              # an example configuration for docker compose
+-- compose-batch.yml                        # an example configuration for a batch process in docker compose
+-- compose-secure.yml                       # an example configuration for docker compose with keycloak and https
+-- README.md

Steps to use your own identity provider

• Make sure, that you have configured your identity provider having a client with clientId and realm matching the values of TOLERANT_CLIENT_ID and TOLERANT_REALM in the .env file
• Remove postgres and keycloak from the compose-secure.yml, this includes services, volumes and depends_on sections.
• Remove the variables INTERNAL_IDENTITY_PROVIDER_URL and INTERNAL_IDENTITY_PROVIDER_PORT from the proxy service in the compose-secure.yml
• Adjust INTERNAL_IDENTITY_PROVIDER_URL and IDENTITY_PROVIDER_URL in the .env file to the URL of your identity provider.
• Remove the mount for the keycloak location from the proxy service in the compose-secure.yml

Steps to use your own ssl certificate

• Remove openssl from the compose-secure.yml, this includes services, volumes_from and depends_on sections.
• Comment in the volumes of the proxy service for ssl certificates in the compose-secure.yml
• Make sure that the ssl certificate and key are under the mounted directory's mentioned in step before
• Make sure that the variables CERT_FILENAME and CERT_PRIVATE_KEY_FILENAME in the .env file match your filenames

Steps to use without gui

Without security

• Replace the mount for the default.conf.template file for proxy with a mount for default.no.gui.conf.template file in the compose.yml
• Remove gui from the compose.yml, this includes services and depends_on sections.

With enabled security

• Replace the mount for the ssl.conf.template file for proxy with a mount for ssl.no.gui.conf.template file in the compose-secure.yml
• Remove gui from the compose-secure.yml, this includes services and depends_on sections.

Usage

Starting

The services can be started using the following commands:

Without security:

docker compose up -d

With enabled security:

docker compose -f compose-secure.yml up -d

The docker compose command should be executed from the directory containing the compose.yml or compose-secure.yml file.

Stopping

The running services can be stopped using the following commands:

Without security:

docker compose down

With enabled security:

docker compose -f compose-secure.yml down

The docker compose command should be executed from the directory containing the compose.yml or compose-secure.yml file.

Starting a batch process

A batch process can be stated with the following example

docker compose -f compose-batch.yml up -d

Removing the container after it has exited

docker compose -f compose-batch.yml down

Steps to use your own configuration and data for a batch process

• mount your configuration and data to the batch container
• adjust the entry point of the compose-batch.yml to match the following pattern:

  entrypoint: ["matchBatch.sh", "<configFilename>", "<projectId>"]

Starting an initial load process

Note The Match backend container must be running to execute this command.
The config file and the data must exist inside the container.

An initial load process can be started using the following commands:

Without security:

docker compose exec backend service.sh backend --endpoint operations --function stop.project --parameter projectId=<projectId>
docker compose exec backend matchInitialLoad.sh [-delete-backlog|-keep-backlog] <configFilename> <projectId>
docker compose exec backend service.sh backend --endpoint operations --function start.project --parameter projectId=<projectId>

With enabled security:

docker compose -f compose-secure.yml exec backend service.sh backend --endpoint operations --function stop.project --parameter projectId=<projectId>
docker compose -f compose-secure.yml exec backend matchInitialLoad.sh [-delete-backlog|-keep-backlog] <configFilename> <projectId>
docker compose -f compose-secure.yml exec backend service.sh backend --endpoint operations --function start.project --parameter projectId=<projectId>

The initial load example can be started using the following commands:

docker compose exec backend service.sh backend --endpoint operations --function stop.project --parameter projectId=matchProject-1
docker compose exec backend matchInitialLoad.sh [-delete-backlog|-keep-backlog] config/matchserviceconfig.xml matchProject-1
docker compose exec backend service.sh backend --endpoint operations --function start.project --parameter projectId=matchProject-1

Match as a cluster (backend only)

Match can be used in a cluster setup for redundancy purposes.

A Match cluster can be started with the following command:

docker compose -f compose-cluster.yml up -d 

The docker compose command should be executed from the directory containing the compose-cluster.yml file, otherwise use the -f parameter for specifying the filepath.

A Match cluster can be stopped with the following command:

docker compose -f compose-cluster.yml down

The docker compose command should be executed from the directory containing the compose-cluster.yml file, otherwise use the -f parameter for specifying the filepath.

Match cluster in kubernetes (backend only)

Match cluster can be used in a kubernetes setup for zero Downtime and Redundancy purposes.

The example kubernetes setup can be started with the following commands:

With dynamic port allocation

kubectl apply -f match-env.yml
kubectl apply -f match-cluster-config.yml
kubectl create -f match-cluster.yml

With a proxy and static port allocation

kubectl apply -f match-env.yml
kubectl apply -f match-cluster-config.yml
kubectl create -f match-cluster.yml
kubectl create -f match-expose.yml

The kubectl commands should be executed from the directory containing the .yml files.

Starting with local user and group

To start with a different user please use the following instructions:

• create the following directories using the local user
  • match-config
  • match-data
  • match-logs
  • match-protocols
• use the fully qualified path of the above mentioned directories in the compose.yml or compose-secure.yml
• comment in the user setting for the backend and the gui service
• start the compose file

Without security:

export UID=`id -u`; export GID=`id -g`; docker compose up -d

With enabled security:

export UID=`id -u`; export GID=`id -g`; docker compose -f compose-secure.yml up -d

The docker compose command should be executed from the directory containing the compose.yml or compose-secure.yml file.

Stopping with local user and group

export UID=`id -u`; export GID=`id -g`; docker compose down

With enabled security:

export UID=`id -u`; export GID=`id -g`; docker compose -f compose-secure.yml down

The docker compose command should be executed from the directory containing the compose.yml or compose-secure.yml file.

License

TOLERANT Match is licensed under a commercial license. This means that the software can only be used for commercial purposes, and that the user must have a valid license to use the software. To get a valid license, please contact support@tolerant-software.de