Verification of the installation

Verifying Your XDM Installation

This section describes how to verify that XDM was installed correctly, that the admin database is available, and that XDM can execute tasks.

Before you start, make sure that the installation and configuration steps described in the following chapters are completed:

The checks in this chapter are grouped into the following areas:

  • Basic checks of containers and admin database

  • Application checks (web UI and a simple smoke test task)

  • Persistence check by restarting the installation

  • Troubleshooting and known issues

Basic Checks

The basic checks ensure that all required services are running and that the admin database is reachable and initialized.

Check Required Containers Or Pods

  • Kubernetes

  • Docker

If you installed XDM using the Helm chart, use the following commands to check the pods:

kubectl get pods --namespace <NAMESPACE>

All XDM pods should be in status Running. Typical pod names include:

  • xdm-core-…​

  • xdm-dataflow-…​

  • xdm-ui-…​

  • xdm-db-…​ (if you use the bundled PostgreSQL database)

  • xdm-grafana-…​ (optional, for monitoring only)

    If pods stay in state Init, Pending, or CrashLoopBackOff, see "Containers Or Pods Not Starting".

Use the following commands to verify that all required XDM containers are running:

cd /opt/xdm                # Change to your XDM base directory
docker compose ps

Ensure that at least the following containers are listed with a running status:

  • xdm3-ui

  • xdm3-core

  • xdm3-dataflow

  • xdm3-db (if you use the bundled PostgreSQL database)

  • xdm3-grafana (optional, for monitoring only)

    If one or more containers are not running, see Containers Or Pods Not Starting.

Check Admin Database Reachability And Initialization

  • Kubernetes

  • Docker

If you use the bundled PostgreSQL database in Kubernetes:

  1. Check that the database pod is running:

    kubectl get pods --namespace <NAMESPACE> | grep xdm-postgres

  2. Describe the pod for detailed information:

    kubectl describe pod <xdm-db-pod-name> --namespace <NAMESPACE>

  3. View the logs to verify that PostgreSQL has started successfully:

    kubectl logs <xdm-db-pod-name> --namespace <NAMESPACE>

    Look for messages that indicate that the database is accepting connections and that no repeated restarts occur. If the pod cannot mount its volume, check the PersistentVolumeClaim and storage configuration in your Helm values file.

If you use the bundled PostgreSQL database container (xdm-db):

  1. Check that the container is running:

    docker compose ps xdm-db

  2. If the container is stopped, restart it:

    docker compose restart xdm-db

  3. Check the database logs for errors:

    docker compose logs xdm-db

    Look for messages that indicate startup problems, such as invalid configuration, missing data directories, or repeated PostgreSQL restarts. If you see frequent PostgreSQL checkpoints or similar performance-related hints, adjust the PostgreSQL configuration according to your environment.

Application Checks

The application checks verify that you can access the web UI, log in with an administrative user, and run a simple smoke test task.

Open The Web UI And Log In

  1. Open a web browser and navigate to the XDM user interface.

    By default, the address is:

    • Kubernetes

    • Docker

    • Kubernetes with Ingress:

      • http(s)://<xdm-domain>/

    Replace <server-name> or <xdm-domain> with the host name or DNS name you configured. If you changed the context path, make sure to include it in the URL.

  2. Log in with a valid username and password. By default, there is an administrative account with the following credentials:

    user: admin
password: default

    If you have changed the usernames and passwords through XDM’s built-in user management or by connecting XDM to an LDAP or OpenID provider, use those credentials instead.

  3. After a successful login, you are redirected to the XDM dashboard.

If you cannot reach the UI or cannot log in, see:

Verify Environment Name And Color

After login, the dashboard shows the current XDM environment. Verify that:

  • The displayed environment name matches your configuration (for example, DEV, TEST, PROD).

  • The environment color (for example, a green or red marker in the header) matches your expectations.

If the environment color is not set as expected, check the configured environment color property in your docker-compose.yml or Helm values file.

Run A Simple Smoke Test Task

To verify that XDM can execute tasks, run a small smoke test task. Any task type that connects to a database and finishes quickly is suitable. For example, you can use:

  • A PII Finder task on a small table, or

  • A minimal read-only task that checks a single table.

Prerequisites:

  • At least one database connection is configured and successfully tested.

  • The required JDBC drivers for your database are installed in the jdbc-drivers directory.

    1. In the XDM UI, click Tasks in the left sidebar to expand the category.

    2. Click Task templates.

    3. Create a small task template that reads from a single table in one of your databases.

    4. Create a task instance based on this template and select the configured database connection.

    5. Click Execute and then Execute and view to start the task.

Wait until the task finishes. The task should complete with status Success. In the Execution logs you should see:

  • The list of stages that were executed.

  • A successful completion without errors.

Persistence Check (Restart Test)

The persistence check verifies that configuration objects and task executions are stored persistently and survive a restart of the installation.

Create Test Objects In The UI

In the XDM UI, create a few small test objects:

  • One or two database connections.

  • A simple application model (for example, a model with a small number of tables).

  • A simple task or workflow that can be executed quickly.

Execute the task at least once so that a task execution with logs is available.

Stop The Installation

  • Kubernetes

  • Docker

To temporarily stop the XDM workloads in Kubernetes, scale the deployments (or stateful sets) to zero replicas. For example:

kubectl scale deployment xdm-core --replicas=0 --namespace <NAMESPACE>
kubectl scale deployment xdm-dataflow --replicas=0 --namespace <NAMESPACE>
kubectl scale deployment xdm-ui --replicas=0 --namespace <NAMESPACE>
kubectl scale deployment xdm-postgres --replicas=0 --namespace <NAMESPACE>   # If you use the bundled database

Adjust the deployment names and namespace according to your Helm chart and cluster setup.

To stop all XDM containers, run:

cd /opt/xdm           # Change to your XDM base directory
docker compose down

This stops and removes all XDM containers, but does not remove data stored in mounted volumes.

Start The Installation Again

  • Kubernetes

  • Docker

To start the XDM workloads again, scale the deployments back to one replica (or to the number of replicas you used before):

kubectl scale deployment xdm-core --replicas=1 --namespace <NAMESPACE>
kubectl scale deployment xdm-dataflow --replicas=1 --namespace <NAMESPACE>
kubectl scale deployment xdm-ui --replicas=1 --namespace <NAMESPACE>
kubectl scale deployment xdm-postgres --replicas=1 --namespace <NAMESPACE>   # If you use the bundled database

Wait until all pods are in status Running:

kubectl get pods --namespace <NAMESPACE>

To start all XDM containers again, run:

cd /opt/xdm           # Change to your XDM base directory
docker compose up -d

Wait until all containers are in status running. Use docker compose ps to verify.

Verify Persistence Of Objects And Logs

  1. Open the XDM UI again and log in.

  2. Verify that all previously created objects are still present:

    • All test connections.

    • The application model.

    • The test task or workflow.

  3. Open the Task executions view and verify that:

    • The previous task executions are still listed.

    • The logs and result information can still be opened.

If Objects Or Logs Are Missing

If some or all objects or logs are missing after the restart, check the volume or PersistentVolume configuration.

  • Kubernetes

  • Docker

In Kubernetes, check the PersistentVolumeClaims (PVCs) used for configuration and data:

kubectl get pvc --namespace <NAMESPACE>

Verify that:

  • All expected PVCs exist (for example, for config, data, tasks, backups).

  • All PVCs are in status Bound.

    If a PVC is not bound, or if the access mode is not compatible with the pods, objects and logs may not be stored correctly. For example, a shared data volume that is mounted by both core and dataflow pods must use a compatible access mode for your storage class.

    If PVCs need to be re-created with different settings (for example, different accessMode or storageClass), plan the changes carefully and ensure that any existing data is backed up before deleting and re-creating the PVCs.

In the file docker-compose.yml, verify that the configuration and data directories are mounted to persistent locations in the host file system. At minimum, check:

  • /xdm/config

  • /xdm/data

  • /xdm/tasks

  • /xdm/backups

  • The directory where the admin database stores its data (if you use the bundled PostgreSQL container)

    Example volume configuration:

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

    If these directories are not mounted, or if they point to non-persistent directories, configuration objects and logs may be lost when containers are removed.

Troubleshooting

This section summarizes typical problems that can occur during installation verification and how to diagnose them.

Containers Or Pods Not Starting

Symptoms:

  • Docker containers exit immediately or are in status restarting.

  • Kubernetes pods are stuck in Init, Pending, or CrashLoopBackOff.

Actions:

  • Check the container or pod logs:

  • Kubernetes

  • Docker

kubectl logs <pod-name> --namespace <NAMESPACE>
docker compose logs <service-name>

  • Look for messages about:

    • Missing files or directories.

    • Permission denied errors when accessing /xdm/config or other mounted directories.

    • Database connection problems.

  • If you run containers as a non-root user, verify that all required directories and files in the host file system have correct ownership and permissions for the configured UID and GID.

UI Not Reachable

Symptoms:

  • Browser cannot connect to the XDM UI.

  • HTTP 404 or 502 errors from a reverse proxy or Ingress.

Actions:

  • Kubernetes

  • Docker

  • Verify that the xdm-ui pod is running.

  • Check the Kubernetes Service and Ingress configuration for XDM.

  • Ensure that the configured domain name points to the correct Ingress controller.

  • If you use a non-default context path (for example, /xdm/ or /prime/), make sure that:

    • The reverse proxy or Ingress forwards the correct path.

    • You include the context path in the browser URL.

  • Verify that the xdm3-ui container is running.

  • Check the port mapping in docker-compose.yml (for example, 4280:80 or 4280:8080).

  • Ensure that firewalls allow access to the configured port.

Login Problems

Symptoms:

  • Login with admin / default does not work.

  • Users from LDAP or OpenID cannot log in.

  • Roles or user attributes (name, e-mail) are not mapped as expected.

Actions:

  • Verify that the user management configuration is correct:

    • Built-in user management: check that the admin password was not changed or disabled.

    • LDAP/AD: check LDAP URL, base DN, bind user, and attribute mappings.

    • OpenID/OAuth2: check client ID, client secret, redirect URL, and scopes.

  • Check the core-server logs for authentication messages. To get detailed information from external authentication providers, increase the log level for Spring Security in the core container:

    logging.level.org.springframework.security=TRACE

    Then restart the core container and inspect the logs for returned roles and user attributes.

For more details about configuring user management and SSO, see the authentication and security chapters in this manual.

Task Failures

Symptoms:

  • Smoke test tasks fail immediately.

  • Task executions show database connection errors.

Actions:

  • Verify that the required JDBC drivers are installed in the jdbc-drivers directory and are readable from the containers.

  • Test the database connection in the Connections view of the UI. Fix any reported errors (for example, wrong host, port, or credentials).

  • Check the task execution logs for:

    • Authentication failures.

    • Timeouts or network connectivity issues.

    • Unsupported SQL or permission errors in the target database.

  • If only tasks for a specific DBMS fail, check whether the JDBC driver for that DBMS is missing or incompatible.

Known Issues And Typical Installation Problems

This section lists common issues that can be detected or confirmed during installation verification.

  • Tasks abort after 24 hours of runtime Long-running tasks may fail when authentication tokens expire. Check your JWT and session timeout configuration in the security settings of XDM and your identity provider.

  • Wrong context path or reverse proxy configuration Incorrect context path or proxy settings can cause HTTP 404 errors or missing internal links in the UI. Ensure that the configured contextPath is consistent between XDM, reverse proxy, and Ingress.

  • Missing or invalid license key If the license key is missing or invalid, services may not start or you may see license errors after login. Verify that the license file is present in the XDM configuration directory and matches your installation. See License key.

  • Missing JDBC drivers If JDBC drivers are missing, tasks for specific database systems will fail immediately with connection errors. Add the correct driver JAR files to the jdbc-drivers directory and restart XDM.

  • Incorrect volume or PVC configuration If configuration and data volumes (Docker) or PersistentVolumeClaims (Kubernetes) are not configured correctly, objects may disappear after a restart. The persistence restart test in "Persistence Check (Restart Test)" will detect such problems.

  • Optional services disabled Optional containers such as Grafana and Prometheus can be disabled if you do not need monitoring and reporting. This does not affect core functionality, but you will not see Grafana dashboards or Prometheus-based metrics.

  • Misconfigured user management or SSO Incorrect LDAP or OpenID configuration leads to login issues, missing roles, or wrong user attributes. See the authentication and security chapters for details on how to configure user management and SSO correctly.