Installation

The main installation package of XDM is the file xdm3-installation.zip. This installation package is designed for systems that are able to download the required Docker containers over an internet connection. This is referred to as an online installation.

If you intend to install XDM on a system that cannot download the required Docker images automatically, you also need the file xdm3-images-installation.zip in addition to the main installation package. This file contains all Docker required containers, and you can register them manually in Docker. This is referred to as an offline installation.

One or both of the files will be provided to you by UBS Hainer as an electronic download.

XDM versions are provided with tags. Tags are simply labels to manage versions. The XDM docker images are provided under the tag latest or under a specific version tag.

Depending on your preferred method, follow the instructions under the section Online installation or the section Offline installation. Afterwards, proceed to section The main XDM configuration file.

After unpacking the XDM installation package and either downloading or registering the Docker containers that belong to XDM, the next steps in the installation process are:

In the file docker-compose.yml, lines that start with the pound sign (#) are treated as comments. Multi-line comments are not supported. If a comment spans multiple lines, each of these lines must start with the pound sign.

Empty lines and lines that only consist of space characters are ignored.

The file docker-compose.yml is divided into multiple sections, each of which may have zero or more parameters and any number of subsections. Parameters may have a single value, or a list of values.

Lists of values are specified by writing the list items into separate lines and prefixing them with a minus sign followed by a space character.

In the following example, there is one top section and one subsection. The subsection has three parameters. The first parameter takes a single value, and the second and third parameter take lists of values.

The structure of the file docker-compose.yml is determined by indentation. Indentation is defined as a zero or more space characters at the start of a line. To maintain portability, it is recommended to avoid tab characters and use spaces instead. In the sample configuration file, four spaces are used per level of indentation. Each node must be indented further than its parent node. All sibling nodes must use the exact same indentation level.

By default, the XDM docker containers must be started under root authorization. If you prefer run XDM under a different user ID, you must repack the docker containers xdm3-ui, xdm3-core and xdm3-dataflow and adjust the file docker-compose.yml.

Follow these steps to run XDM as a non-root user:

To add a parameter to a section in the file docker-compose.yml, open the file in an editor and locate the specified section. Add a new line after its location. Use spaces to create an indentation that is one level deeper than the indentation of the parameter name. Add the new parameter. If the parameter is part of a list of values, make sure that it is prefixed with a minus sign and a space.

It is important to understand how programs running inside Docker containers access the file system of your operating system.

By default, there is no persistent storage defined in the sample file docker-compose.yml. All data will be lost when the containers are removed. You must add folders to the volume mappings if you want the environment to persist.

Applications that run in a Docker container are isolated from the file system of the host operating system. They use their own virtual file system instead. Changes to files and directories that are made by an application inside a container are only visible to that application. These changes will remain if a container is stopped and then started again. However, if a container is removed from Docker (using the docker container rm command), its file system is reset to its original state.

Docker can mount local directories from the host operating system to mount points inside the virtual file system of a Docker container. Mounting local directories to the virtual file systems has the following advantages:

The local directories of the host operating system are also referred to as host directories.

The directories to mount must be specified in the section volumes: inside the file docker-compose.yml. In the sample configuration file, each container has its own set of named volumes.

The syntax for a volume entry is:

- <host-directory>:<virtual-directory>

To mount a volume for read only access, append the suffix :ro to the entry.

If the host system is configured with SELinux, it might be necessary to configure the volume bind mount with the label z.

For more information see the Configure the selinux label section in the docker manual.

After unpacking the XDM installation file into a local directory called xdm, you will get the following directory structure:

Additional files and directories may be present if you downloaded and unpacked the Docker images for an offline installation.

In the sample configuration file, the directory xdm-config is shared between the different Docker containers that XDM uses. Its purpose is to store the license key, additional configuration files, and JDBC driver files (in the sub-directory jdbc-drivers) that need to be accessed from multiple different modules of XDM. Therefore, this directory is also referred to in this manual as the XDM configuration directory.

If you choose to use a different directory as the XDM configuration directory, make sure to change all volume entries in the file docker-compose.yml that use the mount point /xdm/config to the new location inside your local file system.

XDM uses additional directories in its virtual file system which, by default, are not shared with the host system. It is possible to add entries to the configuration file docker-compose.yml in order to associate these directories with locations in your host file system. This allows easy data exchange between the host system, and the Docker environment in which XDM runs.

Doing this is optional. You can change the configuration at any point in time. However, if a virtual directory already contains files at the point in time where you associate it with a directory on the host file system, then the contents of the directory on the host file system will overlay the old contents of virtual directory. You must manually copy the existing data from the virtual directory into the new directory on the host file system to ensure that access to this data is still possible.

For the Admin-Database it is important to have the database being persisted from the docker container via docker mount. Also make sure that the Admin-Database is backed up correctly and that the backup can be restored successfully. When backing up the database it is really important to take a look into the backup file to make sure that the backup was successful. The backup file usually contains any sort of error messages, therefore we recommend to always take a look into the backup file. Otherwise, there is a risk that the backup is damaged and that the database can not be restored.

The backup should also not be placed into the xdm directory. It should be secured in a separate directory outside the server to make it less susceptible for server failure and data loss.