Compose

Last updated: October 26, 2026

Upgrade instructions for Compose-based installations. See Release Notes for the full changelog.

Upgrade Paths

Click a version to expand upgrade instructions. Orange rows are migration boundaries. We recommend taking a VM snapshot or running xltrail backup before upgrading.

⚠️ OIDC-only sign-in — configure your identity provider before upgrading

Version 4.4.0 removes password login, LDAP / Active Directory, password reset and the built-in admin account. Users sign in through your OpenID Connect identity provider (IdP) only. Take a backup first: the migration is irreversible, and you cannot roll back to the previous version without restoring it. If you cannot provide an OIDC identity provider yet, stay on your current release.

1. Register xltrail at your IdP and add the OIDC settings (in /etc/xltrail/xltrail.conf), see Authentication (OIDC). Without them, xltrail starts but nobody can sign in: the sign-in page shows “Single sign-on is not configured”.

2. Remove the settings that are no longer read: AUTH_PROVIDER, LDAP_*, MAX_INVALID_PASSWORD_ATTEMPTS, PASSWORD_RESET_TOKEN_EXPIRY and ADMIN_API_KEY. Rename ON_KUBERNETES to TLS_TERMINATED_UPSTREAM.

3. Make sure every user who should keep access has an account at the IdP with the same email address as in xltrail. Existing users are linked by verified email (not case sensitive) on first sign-in; set OIDC_TRUST_EMAIL=true if the IdP does not mark emails verified. If no existing user, or more than one, has that email, sign-in creates a new user instead, which takes a seat.

4. Give at least one IdP user the administrator claim (OIDC_ADMIN_CLAIM / OIDC_ADMIN_VALUE). Administrator rights come only from that claim; existing admin flags are not kept.

xltrail password no longer works; use docker exec xltrail-server-1 python manage.py users list --admins to check who is an administrator.

During the upgrade, everyone is signed out, and the built-in admin account, the zoomerdebug support account and users of the old replicated auth provider are deleted. Afterwards, only users linked to the IdP count towards seats. Confirm that a real sign-in works before retiring the previous deployment.

4.4.0 latest October 26, 2026


# Standard:
xltrail update -v 4.4.0
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.4.0/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.3.5487 May 28, 2026


# Standard:
xltrail update -v 4.3.5487
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.3.5487/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.3.5166 December 11, 2025


# Standard:
xltrail update -v 4.3.5166
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.3.5166/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.3.4811 July 4, 2025


# Standard:
xltrail update -v 4.3.4811
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.3.4811/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.2.4548 April 28, 2025


# Standard:
xltrail update -v 4.2.4548
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.2.4548/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.12 March 18, 2025


# Standard:
xltrail update -v 4.1.12
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.12/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.11 March 9, 2025


# Standard:
xltrail update -v 4.1.11
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.11/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.10 February 13, 2025


# Standard:
xltrail update -v 4.1.10
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.10/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.8 January 31, 2025


# Standard:
xltrail update -v 4.1.8
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/4.1.8/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.7 October 30, 2024


# Standard:
xltrail update -v 4.1.7
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.7/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.6 October 9, 2024


# Standard:
xltrail update -v 4.1.6
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.6/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

⚠️ Non-root migration — chown required

Since 4.1.6, all containers run as non-root user (UID 1001). When upgrading from < 4.1.6, existing data directories owned by root must be re-owned.

1. Stop the existing stack:


xltrail stop

2. Fix ownership (default DATA_DIR=/var/lib/xltrail):


sudo chown -R 1001:0 $DATA_DIR/source

3. Continue with the standard upgrade for your target version.

Symptom of incorrect ownership: Sync error: repository path '/source/repositories/<repo-id>/origin/' is not owned by current user

4.1.5 September 22, 2024


# Standard:
xltrail update -v 4.1.5
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/4.1.5/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.4 September 13, 2024


# Standard:
xltrail update -v 4.1.4
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.4/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1.3 July 26, 2024


# Standard:
xltrail update -v 4.1.3
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/compose/4.1.3/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

4.1 July 18, 2024


# Standard:
xltrail update -v 4.1
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/4.1/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

⚠️ CLI upgrade + reprocessing (v3.x → v4.0)

⚠️ Requires CLI upgrade. Database backup/restore for air-gapped installations. Triggers reprocessing (may take hours).

1. Upgrade the CLI:


curl -sSL https://downloads.xltrail.com/cli/latest/cli.sh -o /usr/local/bin/xltrail
chmod +x /usr/local/bin/xltrail

2. Standard installation:


xltrail update

Air-gapped installation:


curl -L "https://downloads.xltrail.com/compose/4.0.2/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

When the installation shows Finalizing..., cancel with Ctrl+C — the database needs to be restored first:


xltrail stop
xltrail restoredb
xltrail start

3. Wait for reprocessing — all projects will be reprocessed automatically.

4. Clean up (once everything works) — delete from DATA_DIR (default /var/lib/xltrail): frontend, minio2, source/git, source/xltrail

4.0 major March 28, 2024


# Standard:
xltrail update -v 4.0
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/4.0/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

⚠️ CLI upgrade + reprocessing (v2.x → v3.0)

⚠️ Repositories will be reprocessed (plan for downtime). If upgrading from below v2.10.0 with SSL, perform the SSL config change below first.

1. Upgrade the CLI:


curl -sSL https://downloads.xltrail.com/cli/latest/cli.sh -o /usr/local/bin/xltrail
chmod +x /usr/local/bin/xltrail

2. Upgrade following the standard process. Repositories will be reprocessed automatically.

3.0.0 major July 16, 2020


# Standard:
xltrail update -v 3.0.0
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/3.0.0/bundle.tar.gz" -o bundle.tar.gz
xltrail install -f ./bundle.tar.gz

⚠️ SSL config change (HTTPS only)

⚠️ Required before upgrading from < v2.10.0 if using HTTPS.

Update /etc/xltrail/xltrail.conf:

Before:


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

After:


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

2.10.0

Follow standard upgrade instructions for your target version.

older versions