Configuration

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

License Key

Required. Will be provided to you by email.

LICENSE_KEY=my_license_key

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"

Optional Settings

Auth Provider

If you want to use LDAP to authenticate users, set this to ldap and follow the detailed instructions here.

AUTH_PROVIDER=ldap

Default: app

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. you use an external Git provider or LDAP with a self-signed certificate.

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. If your Git repos sync correctly when disabled (0), disable it for increased security, otherwise leave it at 1. Sometimes 1 is required, e.g. if you’re using a self-signed certificate 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 enable the password reset functionality, you will need to 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

Active Directory / LDAP

xltrail allows central user management via LDAP services such as OpenLDAP or Microsoft's Active Directory.

  • Use quotes around anything that contains a space or special character.
  • After changing the config file, you need to run xltrail restart to apply the changes.
  • LDAP is only available with the Enterprise plan.

A full example

Your /etc/xltrail/xltrail.conf should have entries similar to this:

AUTH_PROVIDER=ldap
LDAP_URL="ldaps://ldap.mycompany.com:636"
LDAP_BIND_DN="serviceaccount@domain.local"
LDAP_BIND_PASSWORD="mypassword"
LDAP_BASE_DN="ou=Users,dc=mycompany,dc=com"
LDAP_USER_DN="{userid}@domain.local"
LDAP_USER_EMAIL_ATTRIBUTE="mail"
LDAP_USER_DISPLAYNAME_ATTRIBUTE="displayName"
LDAP_USER_FILTER="(&(sAMAccountName={userid})(memberOf=cn=xltrail-user,ou=Users,dc=mycompany,dc=com))"
LDAP_ADMIN_FILTER="(&(sAMAccountName={userid})(memberOf=cn=xltrail-admin,ou=Users,dc=mycompany,dc=com))"

Explanations

Start by adding the following setting to the config file (/etc/xltrail/xltrail.conf) to switch from the app internal user management to LDAP:

AUTH_PROVIDER=ldap

Then configure LDAP via the following settings:

LDAP_URL (required)

LDAP server URL. Make sure to provide the correct protocol: ldap or ldaps.

Example:

LDAP_URL="ldap[s]://ldap.mycompany.com:port"
LDAP_BIND_DN (required)

LDAP user with search privileges in the form of a distinguished name (DN). With Active Directory, the domain\myuser or myuser@domain syntax are more common.

Examples:

LDAP_BIND_DN="cn=myuser,dc=domain,dc=com"
LDAP_BIND_DN="mydomain\myuser"
LDAP_BIND_DN="myuser@domain.local"
LDAP_BIND_PASSWORD (required)

The password for LDAP_BIND_DN.

Example:

LDAP_BIND_PASSWORD="mypassword"

To save the password encrypted, use SECURE_LDAP_BIND_PASSWORD instead of LDAP_BIND_PASSWORD and encrypt the password via the xltrail CLI: xltrail encrypt.

LDAP_BASE_DN (required)

The fully qualified DN of an LDAP subtree you want to search for users and groups.

Example:

LDAP_BASE_DN="ou=Users,dc=mycompany,dc=com"
LDAP_USER_DN (required)

The fully qualified DN of the user you need to authenticate when verifying a login. The placeholder {userid} will be replaced with the value that the user types in for username in the xltrail login screen.

Examples:

LDAP_USER_DN="sAMAccountName={userid},ou=Users,dc=mycompany,dc=com"
LDAP_USER_DN="mydomain\{userid}"
LDAP_USER_DN="{userid}@domain.local"
LDAP_USER_FILTER (required)

LDAP search filter for regular xltrail users. The first example is a dummy filter that allows all users.

Examples:

LDAP_USER_FILTER="(sAMAccountName={userid})"
LDAP_USER_FILTER="(&(sAMAccountName={userid})(memberOf=cn=xltrail-user,ou=Users,dc=mycompany,dc=com))"
LDAP_ADMIN_FILTER (required)

LDAP search filter for xltrail admins. Admins have access to settings where they can delete projects, for example.

Examples:

LDAP_ADMIN_FILTER="(sAMAccountName={userid})"
LDAP_ADMIN_FILTER="(&(sAMAccountName={userid})(memberOf=cn=xltrail-admin,ou=Users,dc=mycompany,dc=com))"
LDAP_USER_EMAIL_ATTRIBUTE (required)

Email attribute for user object.

Example:

LDAP_USER_EMAIL_ATTRIBUTE="mail"
LDAP_USER_DISPLAYNAME_ATTRIBUTE (required)

Display name attribute for user object.

Examples:

LDAP_USER_DISPLAYNAME_ATTRIBUTE="displayName"
LDAP_USER_DISPLAYNAME_ATTRIBUTE="cn"

Troubleshooting

To make sure that you are using the correct username/password, verify your settings with ldapsearch.

Note that you should run the following command both for the service account as well as for a sample user.

Make sure to use -H and not -h.

ldapsearch -x \
           -D "mydomain\myuser" \
           -w "password" \
           -H ldap://ldap.mycompany.com:389 \
           -b "ou=Users,dc=mycompany,dc=com"

Instead of using -w "password", you can also use -W which will prompt you to type in the password (without it being shown on screen). This can be useful if you are sharing your screen on a support call.

To test out a specific filter, use it like this:

ldapsearch -x \
           -D "mydomain\myuser" \
           -w "password" \
           -H ldap://ldap.mycompany.com:389 \
           -b "ou=Users,dc=mycompany,dc=com" \
           "(sAMAccountName=myuser@domain.local)"

results matching ""

    No results matching ""