Docker installation on Linux

This section describes how to install XDM on a Linux server using Docker containers. The Docker-based deployment allows you to run all XDM components on a single host with a simple and reproducible setup.

For more information about system requirements, see Requirements. For installation instructions on container orchestration environments, such as Kubernetes or OpenShift, see Kubernetes installation.

Configuration Concept

In a Docker-based installation, configuration is managed in three main places:

The main Docker configuration file <docker-compose.yml> that defines all XDM services.
The XDM configuration directory <xdm-config> that contains the license key, JDBC drivers, and additional configuration files.
Additional host directories for persistent data and logs, mounted into the containers using Docker volumes.

docker-compose.yml

The file <docker-compose.yml> is the main configuration file for an XDM Docker installation. It defines:

Which XDM containers are started (for example core-server, dataflow-server, web-ui, xdm-db, grafana).
Image names and tags (for example docker.ubs-hainer.com/xdm3-core:latest).
Container environment variables, such as license key, database settings, and security options.
Port mappings for the web UI and APIs.
Volume mappings from host directories into the containers.

You customize this file to adapt XDM to your environment (paths, ports, security settings, resources).

XDM Configuration Directory (xdm-config)

When you unpack the installation package into a base directory, it contains a subdirectory <xdm-config>:

xdm
|- docker-compose.yml
|- JDBCSRV.XMIT.BIN
|- README.txt
|- xdm3-jenkins-plugin.hpi
+- xdm-config
   +- jdbc-drivers

In the sample configuration file, <xdm-config> is mounted into the containers at the path < /xdm/config >:

services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro

This directory is used to store:

The XDM version 3 license key file.
Additional configuration files for XDM services.
JDBC driver JAR files in the subdirectory <xdm-config/jdbc-drivers>.

If you use a different directory name or path as the XDM configuration directory, you must update all volume entries in <docker-compose.yml> that mount /xdm/config so that they point to the new location on your host.

Host Directories For Persistent Data And Logs

By default, changes made inside a Docker container are lost when the container is removed. To keep XDM data and logs, you must mount host directories into the containers. These host directories are also called host directories.

Typical persistent host directories include:

./xdm-config – Configuration and license files (as described above).
./xdm-data – XDM admin database and internal metadata (if you use the bundled PostgreSQL container).
./xdm-tasks – Task work directories and result files.
./xdm-backups – Backups produced by XDM tasks.

Volume mappings are configured in <docker-compose.yml>:

services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
      - ./xdm-data:/xdm/data
  dataflow-server:
    volumes:
      - ./xdm-tasks:/xdm/tasks
      - ./xdm-backups:/xdm/backups

Each entry has the format <host-directory>:<container-directory>. To mount a volume read-only, append the suffix :ro:

volumes:
  - ./xdm-config:/xdm/config:ro

If your host uses SELinux, it may be necessary to add the label :z to the volume mapping so that SELinux allows access:

volumes:
  - ./xdm-config:/xdm/config:z
  - ./xdm-data:/xdm/data:z

For details, see the Docker documentation for SELinux labels.

Prerequisites

To install and run XDM with Docker, you need:

Supported Linux Distributions

XDM runs on modern 64-bit Linux systems that support Docker or Podman as a container runtime. Typical examples include:

Red Hat Enterprise Linux (RHEL)
SUSE Linux Enterprise Server (SLES)
Ubuntu LTS

For detailed and up-to-date requirements (kernel version, file system, virtualization), see Requirements.

Docker And docker-compose

On the host server, you must install:

docker – The container runtime.
docker compose – The tool used to start and manage the XDM containers.

XDM cannot be started without Docker and docker compose installed on the host.

Consult the official Docker documentation for installation instructions on your Linux distribution.

Network And Resource Requirements

Your server must provide enough CPU, memory, and disk space for the XDM containers and the task data they process.

Typical minimum resources are:

CPU: Multiple cores (at least one core for the core service plus one core for each parallel task).
Memory: Sufficient RAM for the core, dataflow, UI, database, and monitoring containers (see the Requirements chapter for specific values).
Disk space:
- Space for Docker images and containers.
- Space for XDM task work directories and logs (for example in ./xdm-data, ./xdm-tasks, ./xdm-backups).
Network access:
- Access from the UI to the core server (internal container network).
- Access from XDM containers to your database servers.
- Optional access to the UBS Hainer Docker repository (for online installation).

For detailed hardware and network requirements, see Requirements.

Obtaining And Unpacking The Installation Package

XDM is delivered as zip archives that contain the configuration files and, optionally, pre-packaged Docker images.

There are two variants:

Online installation – Docker pulls the XDM images from the UBS Hainer Docker repository when you first start XDM.
Offline installation – You load pre-packaged Docker images from a local archive.

Obtaining An Installation Package

The main installation package is the file <xdm3-installation.zip>. It contains:

The docker-compose.yml file.
The <xdm-config> directory.
Additional helper files.

For offline installation, you also need <xdm3-images-installation.zip>, which contains the Docker images for all XDM components.

UBS Hainer provides one or both files as electronic download.

Online Installation

Use this procedure if your XDM host can access the internet and connect to the UBS Hainer Docker repository.

Contact XDM Support at <xdm-helpdesk@ubs-hainer.com> and request credentials for the UBS Hainer Docker repository.
Log in to your Linux server via SSH.
Create a base directory for XDM and change to that directory:
```
mkdir -p /opt/xdm
cd /opt/xdm
```
Download the latest base installation package <xdm3-installation.zip> into the base directory. You can use FTP, SCP, wget, curl, or similar tools.
Unpack the installation package:
```
unzip xdm3-installation.zip
```
This creates the docker-compose.yml file and the <xdm-config> directory.
Log in to the UBS Hainer Docker repository:
```
docker login docker.ubs-hainer.com
```
When prompted, enter the credentials provided by UBS Hainer. The credentials are stored in your Docker client configuration.

When you start XDM for the first time, Docker automatically downloads the required XDM images from the repository.

Offline Installation

Use this procedure if your XDM host has no internet access. In this case, you obtain the images on a separate system and transfer them to the XDM host.

Download the following files:
- <xdm3-installation.zip> – Base installation package.
- <xdm3-images-installation.zip> – Docker images package.
Log in to your Linux server via SSH.
Create a base directory for XDM and change to that directory:
```
mkdir -p /opt/xdm
cd /opt/xdm
```
Copy both zip files into the base directory using FTP, SCP, or another transfer method.

Unpack both archives:

unzip xdm3-installation.zip
unzip xdm3-images-installation.zip

Register the Docker images contained in the images package:
```
chmod 775 load-image.sh
./load-image.sh
```
This script loads all XDM images into your local Docker registry and tags them with the tag latest.

When using the images in <docker-compose.yml>, ensure that the image tags match (for example :latest).

Rootless configuration by default

The Docker installation runs by default in a rootless configuration, which means that the Docker containers of XDM are running with the non-root user 1000:1000. This is beneficial for security reasons, as it reduces the attack surface of the system and limits the potential damage that can be caused by a security breach in one of the XDM components.

For more information about the non-root user configuration for XDM, see Non-Root User Container Configuration.

Next Steps

After unpacking the installation package and either downloading or registering the Docker images, continue with:

Customizing <docker-compose.yml> for your environment (see Configuring docker-compose).
Adding the XDM license key (see License key).
Installing the required JDBC drivers in <xdm-config/jdbc-drivers> (see JDBC drivers).
Optionally configuring an external PostgreSQL database instead of the bundled one (see Database configuration).
Starting XDM (see Starting And Stopping The Docker Installation).

Configuring docker-compose

After unpacking the installation package, you must customize <docker-compose.yml> so that XDM fits your environment.

The purpose of this chapter is to explain:

The basic structure of <docker-compose.yml>.
Which parameters must be set before you can start XDM.
How to configure recommended security and usability settings.
How to configure volume mounts for persistent data.

For a full reference of all available Docker Compose options, see the Docker documentation.

Structure Of docker-compose.yml

The <docker-compose.yml> file is a YAML file divided into sections.

Typical top-level sections are:

services: – Defines the XDM containers (for example core-server, dataflow-server, web-ui, xdm-db, grafana).
volumes: – Optional named volumes (not always used in the sample file).
Other standard Docker Compose sections as needed.

Each service (for example core-server) may contain parameters such as image, environment, ports, and volumes:

services:
  core-server:
    image: docker.ubs-hainer.com/xdm3-core:latest
    environment:
      - TZ=Europe/Berlin
      - xdm.core.ui.serverUri=https://xdm-ui:4280/
      - xdm.core.jwt.secret=<your-secret>
    volumes:
      - ./xdm-config:/xdm/config:ro
      - ./xdm-data:/xdm/data
    depends_on:
      - xdm-db

Indentation is done with spaces, not tabs. All child nodes must be indented consistently.

For a generic explanation of YAML structure, comments, and lists, see the existing sections Comments and empty lines and Sections and parameters in this chapter.

Required Parameters

The following parameters must be set before you start XDM:

Depending on the configuration, the following parameter must also be set:

Override Execution User when running Docker as rootless daemon and/or
Disable secure session cookies when using HTTP.

Recommended Parameters

The following parameters are not strictly required to start XDM, but should be configured for production environments.

Optional Parameters

Depending on your environment, you may want to configure additional parameters. These are parameters you should check, if they are useful for your installation:

Context path for the UI via xdm_context_path=xdm/ in services→web-ui→environment,
Activity stream retention via xdm.activity-stream.max-days=<days>,
Automatic cleanup of old executions via xdm.core.executionRetentionPeriod=<duration> and related cleanup settings,
Maximum concurrent tasks via xdm.core.execution.concurrent-tasks=<tasks>,
AI assistance configuration via dedicated environment variables in an ai-assistance service,
Central search configuration via ElasticSearch,
CasC for synchronizing XDM with a git repository and
Logging for fine tuning of logging options.

There are more optional parameters in XDM. Refer to Optional Parameters for more information and further parameters.

Volumes And Mount Points

Volumes and mount points ensure that important data is kept outside the containers and survives container removal.

In <docker-compose.yml>, volumes are configured per service:

services:
  core-server:
     volumes:
      - ./xdm-config:/xdm/config:ro
      - ./xdm-data:/xdm/data
  dataflow-server:
    volumes:
      - ./xdm-tasks:/xdm/tasks
      - ./xdm-backups:/xdm/backups

Each mapping has the form:

- <host-directory>:<virtual-directory>[:options]

Recommendations:

Use a dedicated base directory for all XDM data (for example /opt/xdm).

Create the host directories before starting XDM:

mkdir -p /opt/xdm/xdm-config
mkdir -p /opt/xdm/xdm-data
mkdir -p /opt/xdm/xdm-tasks
mkdir -p /opt/xdm/xdm-backups

Ensure that the Docker user can read and write these directories (ownership and permissions).

If your host uses SELinux, use the :z option as shown earlier.

Starting And Stopping The Docker Installation

After you have configured <docker-compose.yml> and created the required host directories, you can start and stop the XDM Docker installation.

Starting XDM

Log in to your Linux server.
Change to the XDM base directory where <docker-compose.yml> is located:
```
cd /opt/xdm
```
Start XDM in the background:
```
docker compose up -d
```
The -d option runs the containers in detached mode so that they continue running after you close the shell.
To verify that all containers are running, use:
```
docker compose ps
```

If a container is not running, check its logs with:

docker compose logs <service-name>

Stopping XDM

To stop all XDM containers, run:

cd /opt/xdm
docker compose down

This stops and removes the containers, but keeps all data stored in mounted host directories (for example ./xdm-config, ./xdm-data, ./xdm-tasks, ./xdm-backups).

To restart XDM later, run docker compose up -d again in the same base directory.

Connecting To The XDM UI

After XDM is started, open a web browser and connect to the XDM web UI. By default, the UI listens on port 4280 of the host, mapped to the internal HTTP or HTTPS port of the web-ui container.

Use a URL similar to:

http://<server-name>:4280/ – If you use HTTP.
https://<server-name>:4280/ – If HTTPS is enabled in the web-ui configuration.

Replace <server-name> with the host name or IP address of your XDM server.

By default, there is an administrative account with the following credentials:

user: admin
password: default

Use these credentials for the first login. You can then configure user management and change the default password as described in the security chapters.

For detailed steps to log on and verify the installation, see Application Checks.