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
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
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
As root, run the following command to create the new config file and to add the settings required for the installation:
You will be prompted for your
LICENSE_KEY (note that we will send you a new one), the
(also provided by email) and the
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
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
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:
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
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:
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
Change Passwordor by running
xltrail passwordfrom a terminal. Note that you can do the latter anytime to reset the admin password.