Migration to the new xltrail CLI

In April 2019, we introduced a new installer for the self-hosted version of xltrail: The xltrail CLI (command line interface) is fully replacing the management console on port 8800.

While we continue to maintain the legacy installer for existing clients for the running contract period, we recommend to migrate to the new xltrail CLI as it comes with many benefits, see below.

Why a new installer?

Up until now we relied on Replicated to deploy xltrail on premise. The fact that we were dependent on a proprietary 3rd party software component made it difficult for us to deliver fast support whenever something wasn't working out during installation. We also got negative feedback about some of the characteristics of the legacy installer that the new xltrail CLI resolves, see next section.


  • The legacy installer was "phoning home" to verify the license file. xltrail CLI in contrast does the license check completely offline without communicating with any server. This means that you don't have to mess around with your firewall anymore whenever we need to update the license file.
  • The legacy installer was always lagging several months behind the latest release of Docker. xltrail CLI will always support the latest version of Docker so you can keep your system up-to-date and secure.
  • Instead of a proprietary 3rd party Docker scheduler, we now use docker-compose, a widely adopted open-source solution directly maintained by Docker, Inc.
  • The xltrail CLI is smaller in size and uses less system resources than the old platform.
  • The xltrail CLI comes with a very flexible LDAP setup and project permissioning to lock down certain projects to specific users and/or groups.
  • The xltrail CLI features dedicated commands to backup and restore all data that makes it easy to move xltrail to a new server, for example.
  • Except for the http(s) port, the xltrail CLI exposes no other ports, avoiding conflicts with existing services and firewalls.
  • xltrail CLI offers a simplified installation on servers without internet access ("airgapped installations").

How do I migrate?

1. Verify your xltrail and docker version

Verify that you have at least xltrail version 2.3.0 installed (you will see the version number on the management console on port 8800 as Current version). If you are on a lower version, upgrade xltrail first by clicking the button in the management console. Also check your current docker version by running docker -v.

2. Install the xltrail CLI

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

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

3. Config

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

xltrail config

You will be prompted for your LICENSE_KEY (note that we will send you a new one), the DOCKER_REGISTRY_PASSWORD (also provided by email) and the HOSTNAME (e.g. xltrail.yourcompany.com or your IP address).

For any advanced configuration that you changed previously in the management console, keep editing the config file directly under /etc/xltrail/xltrail.conf. For example, to set PROXY_ADDRESS, HTTP_PORT etc., see Configuration.

4. Change the postgres password

Run the following command (note that this requires xltrail to be up and running via the legacy installer):

docker exec -it xltrail-postgres printenv | grep POSTGRES_PASSWORD

This will print the postgres password. Edit the file /etc/xltrail/xltrail.conf and replace the existing value for POSTGRES_PASSWORD with the one you just printed.

5. Stop xltrail from the legacy management console

Go to the management console on port 8800 and click on Stop Now. Wait until it shows Stopped. In case that the command hangs, reboot the machine first.

6. Install docker-compose and upgrade docker

Then, as root, run:

xltrail install-deps

Only if you are on Ubuntu 14.04: Pin your docker version and prevent it from unintentionally updating:

export VERSION=18.06.1; xltrail install-deps
apt-mark hold docker-ce

7. Run the installation

Install xltrail with the same version as the management console shows you as Current Version. Adjust the version number in the command below accordingly, e.g. use 2.5.0 instead of <your version>:

xltrail install -v <your version>

Let the installer finish and double check that the login page appears correctly when you open it in your browser. If you use LDAP, verify that you can login, other move on with the next step.

8. Run the migration

Run the migration:

xltrail migrate

At the end of the process, you should have xltrail up and running again. You can now manage it via the xltrail CLI.

9. Admin password

If you use LDAP, you can ignore this section.

After the migration, the admin password is admin.

NOTE: You have to change the admin password either in the app via the user icon on the top right, then Change Password or by running xltrail password from a terminal. Note that you can do the latter anytime to reset the admin password.

results matching ""

    No results matching ""