Skip to Content
Self-HostingComposeInstallation (Windows)

Installation (Windows Server 2019)

Last updated: October 26, 2026

We highly recommend you to install xltrail on a Linux server. Linux offers a stable environment with a simple installation procedure that is both resource efficient and cheap. The Windows installation requires Windows Server 2019 version 1809 or later and must support Hyper-V/nested virtualization. xltrail on Windows makes use of features that are deemed experimental (Linux containers on Windows “LCOW”).

Known Issues: Starting the application is slow and xltrail needs to be restarted after a server reboot.

1. Requirements

  • Windows Server 2019 version 1809 or later
  • Hyper-V support - on VMs this means that “nested virtualization” must be supported

Currently, Microsoft Azure offers nested virtualization only on their latest generation of virtual machines: D_v3, Ds_v3, E_v3, Es_v3, F2s_v2-F72s_v2, M.

On Azure, select Windows Server 2019 Datacenter as Image and make sure to change the Size to one that supports nested virtualization. We recommend D4s_v3 for xltrail (4 vCPUs / 16 GB RAM).

On AWS, nested virtualization is currently only supported on bare metal servers.

2. Dependencies

All commands in this section must be run in PowerShell with Administrator rights. They are marked with PS>.

2.1 Install Docker, Windows Containers and LCOW

PS> Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
PS> Install-Module "DockerMsftProvider" -Force
PS> Update-Module "DockerMsftProvider"
PS> Install-Package Docker -ProviderName "DockerMsftProvider" -Update -Force

PS> Install-WindowsFeature Containers

PS> mkdir "$Env:ProgramFiles\Linux Containers"; cd "$Env:ProgramFiles\Linux Containers"
PS> curl -OutFile release.zip https://github.com/linuxkit/lcow/releases/download/v4.14.35-v0.3.9/release.zip
PS> Expand-Archive -DestinationPath . .\release.zip
PS> rm release.zip

PS> Restart-Computer

2.2 Start Docker

The following commands enable the experimental Docker features required for LCOW.

PS> Set-Content -Value "`{`"experimental`":true`}" -Path C:\ProgramData\docker\config\daemon.json
PS> restart-service docker

2.3 Windows paging file size

  • Click on the Windows icon and type SystemPropertiesAdvanced.
  • Right-click on it and Run as administrator.
  • On the Advanced tab, select Performance > Settings...
  • In the pop up, go to the Advanced tab and click on Change...
  • Make sure that Automatically manage paging file size for all drives is unchecked
  • Select the [Windows] drive (usually C:), select the System managed size radio button and then make sure to click the Set button.

2.4 Hyper-V

PS> Install-WindowsFeature Hyper-V –IncludeManagementTools –Restart

Windows will restart.

2.5 Docker Compose

Install Docker Compose and fix Docker volume permissions

PS> Invoke-WebRequest "https://github.com/docker/compose/releases/download/1.24.1/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\Docker\docker-compose.exe
PS> icacls C:\ProgramData\docker\volumes /grant *S-1-5-83-0:"(OI)(CI)F" /T

2.6 Git

Go to https://git-scm.com/download/win  and download Git. Alternatively, download the installer like this:

PS> curl -OutFile Git-2.24.0.2-64-bit.exe https://github.com/git-for-windows/git/releases/download/v2.24.0.windows.2/Git-2.24.0.2-64-bit.exe

Double-click the installer and accept all the defaults.

3. xltrail

All xltrail commands (i.e. all commands in this section) must be run with Git Bash, not with PowerShell or Command Prompt. The commands are marked with $. You can paste into Git Bash by doing Shift + Ins or by right-clicking.

3.1 xltrail CLI

$ mkdir -p /etc/xltrail
$ curl -sSL https://downloads.xltrail.com/cli/latest/cli.sh -o /etc/xltrail/xltrail.sh
$ echo 'alias xltrail="bash /etc/xltrail/xltrail.sh"' >> ~/.bash_profile
$ source ~/.bash_profile

3.2 Config

Run the following command to create the config file and to add the settings required for the installation:

$ xltrail config

You will be prompted for the DOCKER_REGISTRY_PASSWORD (provided to you by email) and the HOSTNAME (e.g. IP address or something like xltrail.yourcompany.com).

Then add the OIDC settings for your identity provider (required for signing in, see Authentication (OIDC)) and any other configuration by editing the file directly under C:\Program Files\Git\etc\xltrail\xltrail.conf. For example, if you want to change the data directory, see: Configuration.

Note: Paths require forward slashes, e.g. C:/ProgramData/xltrail

3.3 Install xltrail

$ xltrail install

This will download the docker images and start the application.

NOTE: The very first time you will get a page full of errors. To resolve, simply restart the app:

$ xltrail restart

When the installation is done, type your server’s IP address or domain name (e.g., https://xltrail.mycompany.com ) into a web browser and sign in through your identity provider.

  • Sign-in requires the OIDC settings in xltrail.conf, see Authentication (OIDC). Without them, the sign-in page shows “Single sign-on is not configured”. There is no built-in admin user.
  • Users who should be administrators need the admin claim at your IdP (OIDC_ADMIN_CLAIM / OIDC_ADMIN_VALUE).
  • Once you are signed in, you can add new projects and/or Git integrations, see the Git Projects guide.
  • There is no invitation step: assign users to the xltrail application at your IdP; their account is created the first time they sign in, as long as a seat is free.
Installation (Linux)Configuration