Configuration

Last updated: October 26, 2026

You can configure xltrail via the config file: /etc/xltrail/xltrail.conf. If the file doesn’t exist, create it by running xltrail config.

After changing the config file, you need to run xltrail restart to apply the changes.

The config file does not accept spaces around the = sign.
Comments can be added by starting the line with #.

Mandatory Settings

All mandatory settings are either going to be prompted when you run xltrail config for the first time or will be autogenerated. To change them, you can edit the config file anytime manually.

Docker Registry Password

Required when installing xltrail in online mode via xltrail install. Will be provided to you by email.


DOCKER_REGISTRY_PASSWORD=my_password

Hostname

Required. Your hostname or IP address.


HOSTNAME=xltrail.mycompany.com

Minio Secret Key

This will automatically be set to a random value when you run xltrail config for the first time.


MINIO_SECRET_KEY=...

Postgres

By default, xltrail uses an internal Postgres database and will automatically create a random POSTGRES_PASSWORD when you run xltrail config for the first time.


POSTGRES_PASSWORD=...

If, however, you want to use an external Postgres server, you must create a database called xltrail and provide the additional settings below. Make sure that the user has owner rights so it can run database migrations. A full config for an external database looks as follows:


POSTGRES_HOST="mypostgres.com"
POSTGRES_PORT="5432"
POSTGRES_DB="xltrail"
POSTGRES_USER="xltrail_owner"
POSTGRES_PASSWORD="password"

OIDC

Required for signing in. Users sign in through your OpenID Connect identity provider, see Authentication (OIDC) below.

Optional Settings

BASE_URL

If you don’t want to access xltrail on the root URL, you can define a BASE_URL. For example, to access xltrail on http://my.company.com/xltrail , specify the following setting:


BASE_URL=xltrail

CA_CERTIFICATES

Add a directory with CA certificates. This may be required if e.g. your identity provider or an external Git provider uses a certificate from an internal CA or a self-signed certificate. The certificates are added to the system trust store, which xltrail uses for connections to the identity provider.

The certificates need to have the .crt ending!


CA_CERTIFICATES=/path/to/dir

Data Directory

All data is stored in this directory on your server.


DATA_DIR=/path/to/dir

Default: /var/lib/xltrail

Database check retries


DB_CHECK_RETRIES=20

When running xltrail start or xltrail restart, xltrail exits with exit code 1 if the application can’t establish a database connection after n retries. A retry is done after 5 seconds. By default, the app tries for 20 * 5 sec = 100 secs.

Git integration: Do not verify SSL certificates

This is only relevant if you use the Git integration. Defaults to 1 (SSL certificate verification disabled). Set to 0 to enable SSL verification for increased security, once you have confirmed your Git repos sync correctly. Leave at 1 if you are using self-signed certificates to serve Git repositories over HTTPS.


GIT_SSL_NO_VERIFY=1

Default: GIT_SSL_NO_VERIFY=1

Offline

If you are on a server without internet access, set this flag to stop the CLI from checking for updates.


OFFLINE=1

Default: OFFLINE=0

Ports

You can change the ports on which you want xltrail’s integrated web server (nginx) to listen:


HTTP_PORT=80
HTTPS_PORT=443

Defaults: HTTP_PORT=80 and HTTPS_PORT=443

Proxy Address

If you are behind a proxy server, this is required for online installation and to reach external Git servers. Note that you need to prepare the Docker installation to run correctly behind a proxy, see here . As alternative, you could also use the offline installation.


PROXY_ADDRESS=http://username:password@host:port

SMTP Settings

To send email notifications, configure an SMTP server along the following lines (note that SMTP_SENDER_NAME is optional):


SMTP_HOST=smtp.yourhost.com
SMTP_PORT=587
SMTP_SENDER_EMAIL=contact@yourhost.com
SMTP_SENDER_NAME="xltrail Support"  # optional
SMTP_USERNAME="<yourusername>"
SMTP_PASSWORD="<yourpassword>"

SSL Configuration

If you want to connect to xltrail via https, you need to set the following 4 settings.


HTTPS_ENABLED=1
SSL_DIR=/path/to/dir
SSL_CERTIFICATE_KEY=privkey.pem
SSL_CERTIFICATE=fullchain.pem

Default: HTTPS_ENABLED=0

If TLS terminates at an upstream proxy or load balancer instead, set HTTPS_ENABLED=1 together with TLS_TERMINATED_UPSTREAM=1: nginx then serves plain HTTP while xltrail generates https:// URLs (e.g. the OIDC redirect URI) and marks the session cookie Secure. In this case, SSL_DIR, SSL_CERTIFICATE_KEY and SSL_CERTIFICATE are not needed.


HTTPS_ENABLED=1
TLS_TERMINATED_UPSTREAM=1

Default: TLS_TERMINATED_UPSTREAM=0

Authentication (OIDC)

Since version 4.4.0, users sign in through your OpenID Connect identity provider (IdP) only. Register xltrail at your IdP as described in Authentication (OIDC), then add the settings to /etc/xltrail/xltrail.conf and run xltrail restart. For example, with Microsoft Entra ID:


OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<application-client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_SCOPES="openid profile email"
OIDC_ADMIN_CLAIM=roles
OIDC_ADMIN_VALUE=xltrail-admin

Use quotes around anything that contains a space or special character.

To save the client secret encrypted, use SECURE_OIDC_CLIENT_SECRET instead of OIDC_CLIENT_SECRET and encrypt the secret via the xltrail CLI: xltrail encrypt.

Optional settings: OIDC_TRUST_EMAIL, LOGOUT_REDIRECT_URL and AUTH_TOKEN_EXPIRY. See Authentication (OIDC): Settings for all settings and their defaults.

The redirect URI to register at your IdP is https://<HOSTNAME>/login/oidc/callback (with BASE_URL after the hostname if set, and http:// if HTTPS_ENABLED is off).

AUTH_PROVIDER, LDAP_*, SECURE_LDAP_BIND_PASSWORD, MAX_INVALID_PASSWORD_ATTEMPTS, PASSWORD_RESET_TOKEN_EXPIRY, ADMIN_API_KEY and ON_KUBERNETES are no longer read since 4.4.0; remove them from your config file (use TLS_TERMINATED_UPSTREAM instead of ON_KUBERNETES).