Compose

Last updated: May 29, 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.

4.3.5487 latest May 28, 2026


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

4.3.5166 December 11, 2025


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

4.3.4811 July 4, 2025


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

4.2.4548 April 28, 2025


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

4.1.12 March 18, 2025


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

4.1.11 March 9, 2025


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

4.1.10 February 13, 2025


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

4.1.8 January 31, 2025


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

4.1.7 October 30, 2024


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

4.1.6 October 9, 2024


# Standard:
xltrail update -v 4.1.6
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/xltrail-4.1.6.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.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/xltrail-4.1.5.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.tar.gz

4.1.4 September 13, 2024


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

4.1.3 July 26, 2024


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

4.1 July 18, 2024


# Standard:
xltrail update -v 4.1
 
# Air-gapped:
curl -L "https://downloads.xltrail.com/xltrail-4.1.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.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://www.xltrail.com/cli -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/xltrail-4.0.2.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.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/xltrail-4.0.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.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://www.xltrail.com/cli -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/xltrail-3.0.0.tar.gz" -o xltrail.tar.gz
xltrail install -f ./xltrail.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