Installation (Linux)

1. Requirements

xltrail requires a Linux server capable of running Docker and Docker Compose.

Minimal server configuration:

  • RAM: 4 GB
  • CPU cores: 4
  • Disk space: 50 GB, we recommend 100 GB

2. Dependencies

xltrail requires:

  • Docker (v18.06+)
  • Docker Compose

Install them by following the official docs under your Linux distribution (for RHEL, follow the CentOS instructions):

If you're in a hurry, you can also use the convenience script provided by Docker:

curl -fsSL -o

Double-check that you can run the following two commands:

docker compose

If docker compose isn't available, you can install it as plugin as explained in the official docs:

Or install the Compose standalone by running:

curl -L`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

3. xltrail CLI

xltrail offers a convenient command line interface (CLI) with two installation modes: online and offline. If your server can't access the internet ("air-gapped server"), then you need to expand the Offline Installation sections below and follow the instructions contained therein.

As root, install the xltrail CLI (command line interface):

curl -sSL -o /usr/local/bin/xltrail
chmod +x /usr/local/bin/xltrail

You can get an overview of the available commands by typing xltrail in your terminal.

Most commands require that you run them as root. If you add your user to the docker group, then you'll only need sudo for install and update. To add your user to the docker group, run sudo usermod -aG docker $USER once docker is installed on your system (see Dependencies below). The docker group grants privileges equivalent to the root user, see also the Docker documentation.

Offline Installation (click to expand) Nothing special to be done here, except transferring the xltrail file manually to the air-gapped machine.

4. Config

As root, run the following command to create the config file and to add the required settings:

xltrail config

You will be prompted for your LICENSE_KEY, the DOCKER_REGISTRY_PASSWORD (both provided to you by email) and the HOSTNAME (e.g. IP address or something like

For any advanced configuration (such as TLS), edit the file directly under /etc/xltrail/xltrail.conf, see Configuration.

xltrail will install its configuration files under /etc/xltrail. If you want to change that, you can set the XLTRAIL_CONFIG_DIR environment variable:

export XLTRAIL_CONFIG_DIR=/my/path
xltrail config
Offline Installation (click to expand) When running xltrail config, you can leave the DOCKER_REGISTRY_PASSWORD empty. Once the config file has been created, edit /etc/xltrail/xltrail.conf directly to add the following line: OFFLINE=1.

5. xltrail

To install xltrail, type the following command as root:

xltrail install

This will download the docker images and start the application.

Offline Installation (click to expand)

To install xltrail in offline mode, you need to download the application bundle like this, then transfer it over to the air-gapped machine:

curl -L "" -o xltrail.tar.gz

Then, instead of xltrail install, run the installer as follows:

xltrail install -f ./xltrail.tar.gz

6. Login

When the installation is done, type your server's IP address or domain name (e.g., into a web browser and login with both username and password admin.

  • Once you are logged in, you can add new projects and/or Git integrations, see here.
  • You can add users manually by going to the user icon on the top right, then Settings > Team. If you would rather want to connect xltrail with your LDAP/AD directory, have a look at the LDAP docs.

You have to change the admin password either in the app via the user icon on the top right > Settings > Password or by running xltrail password from a terminal. You can do the latter anytime to reset the admin password.

results matching ""

    No results matching ""