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). 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 granular project access management 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 Docker and xltrail version

  • Verify that you have at least Docker version 18.06 installed. If you don't, first re-run the legacy installation script, see here.

    docker -v
  • 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.

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).

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.

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. Install docker-compose

As root, install docker-compose:

curl -L https://github.com/docker/compose/releases/download/1.24.0/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

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.

6. 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. Do not login at this point, but move on with the next step.

7. 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.

8. Admin password

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 ""