Install Semarchy xDM on Docker
This page guides you through the step-by-step process of installing Semarchy xDM with Docker Compose.
This set of instructions assumes you have Docker and Docker Compose installed and running. For more details, see the official Docker documentation. |
Docker images
Base image
Semarchy xDM images are using an official Tomcat base image composed of:
-
A Tomcat version supported by xDM (see System requirements).
-
A Debian image.
-
An OpenJDK version supported by xDM (see System requirements).
Active and passive server images
There are two types of images available for Semarchy xDM:
-
Active server images are used to host the actively serving instances of xDM.
-
Passive server images are used to run passive instances of xDM for high availability.
All images are available on the Docker Hub platform.
Use Docker compose
The following Docker Compose sample configuration file can be used as a template. It configures a container aimed at deploying an instance of the specified xDM version.
Platform administrators deploying this configuration need to customize parameters such as the version, database connection details, credentials, setup token, context path, and any other relevant settings to align with the specific requirements of their deployment. For proper configuration of all properties within a given environment, see Startup configuration. |
version: '3.8'
services:
semarchy-appserver:
image: semarchy/xdm:<version>
# Specify version (e.g., 2024.1.0).
ports:
- '8088:8080'
networks:
- semarchy-net
healthcheck:
test: [ "CMD", "./semarchy_healthcheck.sh" ]
environment:
# Repository connection:
- XDM_REPOSITORY_DRIVER=<repository_jdbc_driver_class>
- XDM_REPOSITORY_URL=<repository_jdbc_url>
# Reconfigure this connection to use a separate database.
# Repository datasource credentials:
- XDM_REPOSITORY_USERNAME=<repository_user>
- XDM_REPOSITORY_PASSWORD=<repository_password>
# Repository read-only datasource credentials:
- XDM_REPOSITORY_READONLY_USERNAME=<repository_readonly_user>
- XDM_REPOSITORY_READONLY_PASSWORD=<repository_readonly_password>
# Setup token:
- SEMARCHY_SETUP_TOKEN=<setup_token>
# (Optional) Customizable context path:
- CONTEXT_PATH=<context_path>
# - If not present: http://localhost:8088/semarchy
# - If blank value: http://localhost:8088/
# - If present: must start with a forward slash (/)
# Add other startup configuration properties (e.g., secrets management configuration).
volumes:
# Volume for additional JAR libraries:
- ./additional-libraries:/usr/local/tomcat/additional-libraries
This YAML file defines the services and volumes to run and use in an xDM container, but does not provide configurations to set up a database instance. Platform administrators should configure the database connection parameters accordingly. To define a proper startup sequence, the Additionally, the top-level |
Semarchy provides an example of how to combine xDM with a database and automatically create database schemas using a single Docker Compose sample file available on Docker Hub. |
Configure Semarchy xDM Docker images
The configuration options for Semarchy xDM Docker images are as follows.
-
Supported parameters:
-
xDM startup configuration environment variables: used for configuring essential settings such as initial login, database access, and more. For detailed information, see xDM startup configuration.
-
CATALINA_OPTS
: used for defining system properties. -
JVM_MEMORY_OPTS
: used for setting Java Virtual Machine memory options (defaults to-XX:MaxRAMPercentage=75
).
-
-
Additional libraries: third-party libraries can be added by mounting a volume on
/usr/local/tomcat/additional-libraries
. -
Custom configuration: custom configurations that involve modifying
server.xml
orsemarchy.xml
require creating a custom image.
Run xDM with Docker Compose
To run the application server and database containers:
-
From the directory where your xDM Docker Compose project is located, start up your application by running the following command:
$ docker compose -f <docker_compose.yml> up
-
Visit http://<container-ip>:8080/semarchy in a browser to see the application running.
Logs
According to the logging configuration specified in Docker, all logs generated by the Semarchy xDM container are redirected to the container log system.
Image tags
Various Semarchy xDM Docker image tags are available for different use cases:
-
xdm:latest
: latest xDM active server (semarchy.war
). For more details, see Semarchy xDM Architecture.This is the main image to use for single-node implementation and for the active node used in high-availability configurations.
It is not recommended to use this tag in production, as it automatically upgrades to the latest version published by Semarchy. This active server image should never be started more than once per repository. -
xdm:latest-passive
: latest xDM passive server (semarchy-passive.war
) for high-availability configurations. For more details, see Semarchy xDM Architecture.It is not recommended to use this tag in production, as it automatically upgrades to the latest version published by Semarchy. -
xdm:<minor_version>
: latest version for a specific minor version of xDM active server (semarchy.war
).It is not recommended to use this tag in production, as it automatically upgrades to the latest version published by Semarchy. -
xdm:<minor_version>-passive
: latest version for a specific minor version of xDM passive server (semarchy-passive.war
).It is not recommended to use this tag in production, as it automatically upgrades to the latest version published by Semarchy. -
xdm:<full_version>
: specific full version of xDM active server (semarchy.war
). -
xdm:<full_version>-passive
: specific full version of xDM passive server (semarchy-passive.war
).