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:

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.
Sample configuration file
version: '3.8'

services:
  semarchy-appserver:
    image: semarchy/xdm:<version>
     # Specify version (e.g., 2024.1.0).
    ports:
      - '8088:8080'
        networks:
      - <network>
    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 absent: http://localhost:8088/
        # - 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 depends_on option can be configured so that xDM starts only after a dependent database service is up and healthy.

Additionally, the top-level networks element can be included to define specific network configurations for the xDM container.
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 or semarchy.xml require creating a custom image.

Run xDM with Docker Compose

To run the application server and database containers:

  1. 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

  1. 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).