Installation

This chapter describes how to install, verify, update, back up and maintain XDM. It covers both supported installation types (Kubernetes and Docker on a Linux server).

Scope And Audience

This chapter is intended for administrators and DevOps engineers who install and operate XDM in their own infrastructure. It focuses on infrastructure layout, runtime configuration and integration into existing platforms such as Linux servers or container‑orchestration environments.

XDM provides a web user interface that is accessed via a browser. All configuration, administration, test data ordering and monitoring is performed against a centrally installed XDM instance.

Prerequisites, supported platforms and detailed hardware and software requirements (for example supported operating systems, database versions and minimum resources) are documented in the Requirements chapter. Before starting any installation, ensure that these requirements are fulfilled.

Installation Variants

XDM is delivered as container images and is designed to run in containerized environments. There are two main installation variants:

Kubernetes‑based installation (for example Kubernetes or OpenShift using Helm)
Docker‑based installation on a Linux server

Both variants use the same set of XDM services (such as core server, dataflow server, UI and administration database), but they differ in how these services are deployed, scaled and operated.

Kubernetes-Based Installation (For Example Kubernetes, OpenShift)

In this variant, XDM is deployed into a Kubernetes or OpenShift cluster using the provided Helm chart. The chart defines deployments, services, persistent volumes and optional components such as monitoring dashboards, and allows you to manage XDM like any other cloud‑native workload.

This installation type is usually the best choice when:

Your organization already operates Kubernetes or OpenShift as a standard platform for applications.
You need horizontal scalability for XDM services, for example to handle many concurrent task executions.
You require advanced high‑availability concepts, rolling upgrades and cluster‑level resource management provided by Kubernetes.
You want to integrate XDM into an existing platform ecosystem with centralized logging, monitoring and storage classes.

Typical characteristics of the Kubernetes‑based installation include:

All XDM services are deployed as pods, managed via deployments or stateful sets.
Persistent volumes are used for the administration database and shared data directories (for example task work directories and logs).
Access modes and storage classes must be chosen carefully, especially for volumes shared between core and dataflow pods (for example using ReadWriteMany where multiple pods access the same volume).
Helm values control environment variables, resource limits, persistence, ingress and TLS configuration.

Choose the Kubernetes‑based installation if XDM is part of a broader, container‑oriented platform strategy, if you need elastic scaling for test data workloads, or if your operational standards require automated deployment and lifecycle management via Helm and Kubernetes.

Docker-Based Installation On A Linux Server

In this variant, all XDM services run as Docker (or Podman) containers on a single Linux host. A typical setup uses a docker-compose.yml file to define and start the services.

This installation type is usually the best choice when:

You want a straightforward, self‑contained installation on a dedicated Linux server.
Your organization does not use Kubernetes or similar orchestration platforms, or you prefer to manage only one host manually.
You are running a proof‑of‑concept, pilot, development or smaller production setup, where a single server is sufficient.
You want to minimize initial operational complexity and rely on the containerization and separation provided by Docker.

In a Docker‑based installation, scaling is typically done by assigning sufficient CPU and memory resources to the host and tuning XDM parameters such as the number of concurrent task executions and memory per task.

Components of an XDM installation

XDM consists of multiple program modules. These modules are located in the following containers:

Table 1. Components in XDM
Service Name	Image Name	Description	Requirement Level
web-ui	docker.ubs-hainer.com/xdm3-ui:<version>	An interactive browser-based user interface that allows end users and administrators to configure XDM, request test data, monitor executions, and review logs and reports	required
core-server	docker.ubs-hainer.com/xdm3-core:<version>	Core application service that provides the central REST API, configuration management, security, workflows and overall business logic required to operate XDM.	required
dataflow-server	docker.ubs-hainer.com/xdm3-dataflow:<version>	Dataflow and task execution engine that runs XDM tasks and workflows as standalone programs, either inside the container or in an own pod, for processing data on the connected database systems.	required
xdm-db	docker.ubs-hainer.com/postgres:15	PostgreSQL administration database used by XDM to store configuration, metadata, logs, histories and session information.	required
loki	docker.ubs-hainer.com/xdm3-loki:<version>	Central log aggregation service for collecting and querying XDM logs, referenced in the dataflow configuration.	required
tempo	docker.ubs-hainer.com/xdm3-tempo:<version>	Distributed tracing backend (Zipkin‑compatible) used for collecting trace data from XDM.	required
grafana	docker.ubs-hainer.com/xdm3-grafana:<version>	A service that provides dashboards and visualizations for XDM usage and system metrics; connects to Prometheus and XDM’s PostgreSQL database.	recommended, required for monitoring/reporting
prometheus	docker.ubs-hainer.com/xdm3-prometheus:<version>	A service that collects metrics from XDM services (Core and Dataflow) and stores them for monitoring and reporting. Typically used as the metrics backend for Grafana dashboards.	recommended, required for monitoring
elasticsearch	docker.ubs-hainer.com/elasticsearch:7.17.25	A service used as a full-text and analytics index for XDM to provide a global search in XDM.	recommended, required for global search
neo4j	docker.ubs-hainer.com/neo4j:4.4	A graph database used by XDM to store and query application models, relations and graph-based metadata for tasks and environments. It allows XDM to resolve complex relationships between tables and entities during selection and copy operations.	required for Test Data Finder
ai-assistance	docker.ubs-hainer.com/xdm3-ai-assistance:<version>	A service that provides intelligent support for XDM using AI, for example by helping to generate or refine test data definitions and configuration snippets using large language models.	only necessary for AI Assistance option
generator-source	docker.ubs-hainer.com/xdm3-generator-source:<version>	A service that produces synthetic or sample data as an input stream for XDM tasks. With this, XDM is able to generate data, e.g. for performance for functional testing.	required for Test Data Generation
file-sink	docker.ubs-hainer.com/xdm3-file-sink:<version>	A service that writes generated data produced by XDM into files (for example CSV or other structured formats) instead of a database target. It allows XDM to export generated data into external file system	s. (required for Test Data Generation
graph-store	docker.ubs-hainer.com/xdm3-graph-store:<version>	A dedicated service that persists graph representations of XDM configuration and data relationships for webservices and data generation used in XDM (for example larger models or specific analytics).	only necessary for webservices used in XDM
sample-ssh	docker.ubs-hainer.com/linuxserver/openssh-server:version-9.0_p1-r2	A container that exposes a simple SSH/SFTP endpoint used for the tutorial. It allows users to try out SSH-based integrations without connecting to a real corporate server.	only for tutorial necessary
sample-pg	docker.ubs-hainer.com/sample-environment:latest	A sample PostgreSQL database used for the tutorial. It provides a predefined schema and data so that users can experiment with selections, copies and modifications without connecting to their own databases.	only for tutorial necessary
prime-ui	docker.ubs-hainer.com/xdm3-prime-ui:<version>	A refactored interactive browser-based user interface that allows end users and administrators to configure XDM, request test data, monitor executions, and review logs and reports	optional

XDM Directories And File Locations

XDM uses several internal directories to store configuration, working data and backups. These directories are represented inside the XDM runtime as virtual directories under the /xdm path. Depending on your deployment model, you can associate these virtual directories with locations on your host file system.

Associating virtual directories with host directories is required for:

Persisting XDM data across restarts or upgrades,
Exchanging files between XDM and other tools,
Simplifying backup and restore procedures.

You can change the directory configuration at any point in time. However, if a virtual directory already contains files when you associate it with a directory on the host file system, the contents of the host directory will overlay the previous contents of the virtual directory. You must manually copy any existing data from the virtual directory into the new host directory if you want to keep access to this data.

Overview Of Virtual Directories

The following virtual directories are used by XDM:

/xdm/data – General data exchange between XDM and the host system.
/xdm/tasks – Task working files and extracted data previews.
/xdm/backups – IceBox backup generations created by XDM.
/xdm/mapping – H2 databases for mapping table containers.
/xdm/config – XDM configuration files (for example custom properties).

In most installations these virtual directories are mapped to persistent host directories, either via container volume configuration or via the operating system’s file system configuration. For details on how to configure these mappings in your specific deployment model, refer to the setup and configuration chapter of this manual.

Data Exchange Directory (/xdm/data)

The virtual directory /xdm/data can be used for general data exchange between the host system and XDM. You can use this directory to provide, among other things:

Files that are written by extract data rules,
Files that contain additional dictionaries for the purpose of searching for PII,
Configuration as code definitions,
Helper files that may be referenced by modification methods.

When /xdm/data is associated with a host directory, any files that you place in the host directory become available to XDM tasks that read from /xdm/data. Conversely, tasks or workflows can write files into /xdm/data, and these files will be visible on the host system.

Task Working Directory (/xdm/tasks)

The virtual directory /xdm/tasks is used to store files that are created and used during the execution of XDM tasks. Typical contents include:

Temporary unload and load files,
Intermediate transformation files,
Data used by the schema browser to display extracted data from subset extracts.

Associating a host directory with /xdm/tasks gains direct access to these task work files from the host system. This is useful for:

Troubleshooting and manual inspection of task results,
Integrating with external tools that need to post-process task output.

Because task executions can create large amounts of data, make sure that the host directory used for /xdm/tasks is located on a file system with sufficient capacity and appropriate performance.

IceBox Backup Directory (/xdm/backups)

The virtual directory /xdm/backups is used to store IceBox generations and backups created by XDM. These backups contain tagged and versioned test data that can be restored or reused in later task executions.

Associating /xdm/backups with a persistent host directory allows to:

Protect IceBox data against loss when XDM services are restarted or updated,
Include IceBox generations in your regular backup strategy,
Move IceBox data between systems if required.

The host directory used for /xdm/backups should be:

Persistent across system restarts and software updates,
Regularly backed up according to your organization’s policies,
Sized to handle the expected volume and retention period of IceBox generations.

Mapping Directory (/xdm/mapping)

The virtual directory /xdm/mapping is used to store H2 database files. These databases contain the data and metadata for mapping tables that are used in modification and transformation processes.

When you map /xdm/mapping to a host directory, the H2 database files become directly accessible on the host system. This makes it easier to:

Back up and restore mapping tables,
Move mapping table data between environments,
Monitor disk usage of mapping table storage.

As with other directories that contain important configuration or reference data, the host directory for /xdm/mapping should be persistent and part of your backup strategy.

Configuration Directory (/xdm/config)

The virtual directory /xdm/config is used by XDM to store configuration files, for example:

XDM license key, if stored in a file,
JDBC drivers for databases.

Mapping /xdm/config to a host directory allows to:

Persist configuration across container or service updates,
Integrate XDM configuration into your existing backup and change management processes.

Requirements For Stable Installations

To provide a stable installation and prevent data loss, keep the following in mind:

Install XDM into a persistent base directory on the host system, for example /opt/xdm.
Ensure that this base directory and all associated data directories are protected by regular backups, so that you can restore XDM data in case of a server failure.
Verify that the following virtual directories are correctly associated with persistent storage in all XDM services that require them:
- /xdm/tasks in data flow and core services,
- /xdm/data in data flow and core services,
- /xdm/backups in data flow services,
- /xdm/config in data flow and core services,
- File Bridge directories, if the File Bridge component is in use.
When running XDM on an orchestrated platform (such as Kubernetes or OpenShift), make sure that all volumes backing these directories are configured as persistent volumes with appropriate storage classes and retention policies, if File System Storage is used.

Properly configuring and protecting these directories ensures that:

Task executions can complete reliably,
IceBox generations and mapping data are preserved,
Configuration changes are not lost during maintenance activities.

XDM Administration Database

The administration database is the central database used by XDM to store its own configuration and operational data. It is required for every XDM installation, independent of the installation method (Docker, Podman, Kubernetes, OpenShift, or other container runtimes).

XDM does not store test data or business data in the administration database. Those data sets remain in the connected source and target systems that you configure in XDM.

Purpose Of The Administration Database

The administration database provides persistent storage for all objects that define and control your XDM installation. Without this database, XDM cannot:

store configuration objects such as connections, environments, tasks, workflows, and Data Shop definitions,
maintain the domain and application models that describe your business applications,
record task executions and keep technical logs and reports for later analysis,
manage users, roles, and permissions (when internal user management is used),
store internal system settings and Scheduler information.

The administration database is therefore a mandatory component of every XDM system.

Data Stored In The Administration Database

The following categories of data are stored in the administration database:

Configuration objects

XDM stores all configuration objects that define how test data is provided. Typical examples include:

connections to source and target systems,
environments and application models,
task templates and concrete tasks,
workflows and Data Shop configurations.

Metamodels and application models

XDM stores the imported database schemas and the relations between tables that are used for row‑level processing and domain modelling. These models describe how business objects are represented in the underlying databases.

Execution and reporting data

Each time a task is executed, XDM creates a task execution entry with status information, logs, and optional reports. These records are used for monitoring, troubleshooting, and audit purposes.

System and operational data

The administration database contains internal data required for operating the platform, for example:

configuration history and object versioning,
scheduler definitions for planned executions,
internal sessions and metrics used by dashboards such as Grafana.

The administration database does not contain the test data itself. Instead, XDM reads and writes test data directly in the connected databases or file systems.

Supported Database System And Deployment Options

XDM uses PostgreSQL as its administration database. The database can be provided in different ways, depending on your preferred deployment model:

Internal PostgreSQL instance running as a container, managed by the XDM deployment (for example, as a Docker container or a Kubernetes Pod).
External PostgreSQL instance that is operated and managed by your database team.

The choice between an internal or external instance does not change what XDM stores in the administration database. It only affects how the database is provisioned, monitored, and backed up.

XDM Versioning

XDM is delivered in clearly versioned releases. Each release is identified by a version tag. Tags are labels that allow you to select and manage specific XDM versions across different delivery channels (for example container images or installation packages).

Version Tags And Naming Scheme

XDM release versions follow the pattern 3.YY.WW.

3 – The major XDM version.
YY – The last two digits of the calendar year in which the release is published.
WW – The calendar week of the release within that year.

For example, the tag 3.26.11 refers to an XDM release from calendar week 11 in the year 2026.

This version tag is used consistently in all XDM delivery artifacts, such as:

Container images for the XDM services,
Helm charts or other deployment descriptors that reference a concrete XDM version,
Installation or upgrade packages, where applicable.

Using a fixed version tag ensures that you always know exactly which XDM release is installed in a given environment.

Minor releases use the version pattern 3.YY.WW-N with an additional number N, hotfixes the version pattern 3.YY.WW-XHLP-NNNN.

In addition to the explicit version tags, XDM it also be provided under a generic latest tag. The latest tag always points to the newest and most recently published stable release. It is used in the default installation files.

During the installation, the latest tag must be replaced by the tag of the version to install.

Before a new stable release is published, a pre‑release version can be available under the same 3.YY.WW version tag for a limited time. Do not install this pre-release version because it is not complete tested at this point.