Install

For a Linux server you own. Pull the image, or download a release from GitHub.

  • Linux, amd64 or arm64
  • Docker 24+ set up for you
  • Ports 80 and 443
  • 1 vCPU, 1 GB, 10 GB

A single node is the well-tested path and multi-node is in beta. Pre-releases are only installed if you choose the beta channel.

What is new in v1.5.6
  • render the demo GTM loader in the HTML head and run the demo on v1.5.5
Full release notes
root@your-server
docker pull ghcr.io/glincker/levelrail:latest# Multi-arch image for linux/amd64 and linux/arm64, signed with cosign# Run it with the docker run example further down# Then print the one-time setup token for the first admin

Download from GitHub View install instructions on GitHub

The path

From a bare server to a first app

Four steps, about five minutes. These are real screens from a fresh install.

  1. Step 1

    Start the server

    Pull the image and run it on a Linux host with Docker, or download a release from GitHub.

  2. Step 2

    Copy the setup token

    The summary prints the dashboard URL and a one-time token. Valid for 15 minutes, print a new one any time.

  3. Step 3

    Create the admin

    Open the setup link, paste the token and pick a username and password.

    The Set up the admin account page with fields for setup token, username and password.
  4. Step 4

    Deploy a first app

    The sample app goes healthy with an automatic address. Then enable HTTPS from Domains.

    The sample app overview with a green Healthy pill and its generated address.

Before you start

Requirements

  • OS

    Linux, systemd

    Linux, amd64 or arm64, with systemd. Tested in CI on Ubuntu 24.04 and Debian 12. Other distros should work but are untested. Windows and other non-Linux systems are not supported.

  • Docker

    Docker 24+

    24 or newer. The installer sets it up through get.docker.com if it is missing.

  • Access

    Root and curl

    Root on the host.

  • Ports on the control plane node

    80/tcp, 443/tcp

    80/tcp and 443/tcp inbound. Port 80 is needed for Let's Encrypt HTTP-01. 443/udp is optional, for HTTP/3.

  • Ports on agent-only nodes

    No inbound ports

    None. Agents dial out to the control plane.

  • Starting size

    1 vCPU, 1 GB, 10 GB

    1 vCPU, 1 GB RAM and 10 GB disk boots Docker and the control plane. 2 vCPU, 2 GB RAM and 20 GB disk is more comfortable once builds and apps run. No minimum has been benchmarked or published yet.

Supported hosts: any Linux server with systemd on amd64 or arm64, such as a home server, a VPS, an EC2 instance or a Google Cloud VM. The installer has no distro allowlist, it checks for Linux, systemd, curl and a usable Docker. Ubuntu 24.04 and Debian 12 are the ones tested in CI, so treat other distros as untested.

Downloads

Pick your platform

Every file below is from the v1.5.6 release on GitHub. Verify the checksum before you run a binary.

Linux amd64

For a first install, use the one-line command at the top: it also writes the systemd unit and prints your setup token. These commands download the bare binary, check it and put it in place, which is the manual route.

levelrail-linux-amd64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/levelrail-linux-amd64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/checksums.txt
sha256sum --ignore-missing -c checksums.txt
chmod +x levelrail-linux-amd64
sudo install -m 0755 levelrail-linux-amd64 /usr/local/bin/levelrail

Expected SHA-256 for v1.5.6

9179101c32baa573c150dd9cbacb559983d37d14727c1365c60836baf018ce6f  levelrail-linux-amd64

Linux arm64

levelrail-linux-arm64Control plane, 343 MB
  • ARM64 (aarch64)
  • 343 MB
  • v1.5.6

For a first install, use the one-line command at the top: it also writes the systemd unit and prints your setup token. These commands download the bare binary, check it and put it in place, which is the manual route.

levelrail-linux-arm64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/levelrail-linux-arm64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/checksums.txt
sha256sum --ignore-missing -c checksums.txt
chmod +x levelrail-linux-arm64
sudo install -m 0755 levelrail-linux-arm64 /usr/local/bin/levelrail

Expected SHA-256 for v1.5.6

bc17a8dbf76898c1c051cf2f594e9aa5e745e9e057275a78949ded23811eb551  levelrail-linux-arm64

Docker

Multi-arch images for linux/amd64 and linux/arm64, signed with cosign. Pin the exact tag for anything you care about staying still.

pull
docker pull ghcr.io/glincker/levelrail:v1.5.6
docker pull ghcr.io/glincker/levelrail-agent:v1.5.6
docker run
docker run -d \
  --name levelrail \
  -p 80:80 -p 443:443 -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  -v levelrail-data:/var/lib/levelrail-data \
  -e APP_DATA_DIR=/var/lib/levelrail-data \
  ghcr.io/glincker/levelrail:v1.5.6

Port 8080 is bound to the loopback address. Tunnel to it for the first sign-in, then print the setup token from inside the container. The container gets access to the Docker socket, so only run it on a host you already trust with that.

first sign-in
ssh -L 8080:127.0.0.1:8080 user@your-server
docker exec levelrail levelrail setup-token

Moving tags: :latest and :v0.8 follow stable releases, :beta follows pre-releases.

Command line tool

To control an existing instance from your laptop or a CI runner, install just the CLI with Homebrew. It is a client, not the server.

brew install glincker/tap/levelrail-cli

Or download the binary yourself:

  • macOS amd64levelrail-cli-darwin-amd64, 150 MB Download
  • macOS arm64levelrail-cli-darwin-arm64, 141 MB Download
  • Linux amd64levelrail-cli-linux-amd64, 146 MB Download
  • Linux arm64levelrail-cli-linux-arm64, 136 MB Download
  • Windows amd64levelrail-cli-windows-amd64.exe, 145 MB Download
  • Windows arm64levelrail-cli-windows-arm64.exe, 134 MB Download

Verify

Check what you downloaded

Every release file is listed in checksums.txt, and checksums.txt itself is signed with cosign keyless signing from this repository's release workflow.

1. SHA-256 checksum

Run it in the folder with the file and checksums.txt. It skips files you did not download.

checksum
sha256sum --ignore-missing -c checksums.txt
9179101c32baa573c150dd9cbacb559983d37d14727c1365c60836baf018ce6f  levelrail-linux-amd64
bc17a8dbf76898c1c051cf2f594e9aa5e745e9e057275a78949ded23811eb551  levelrail-linux-arm64

2. Signature on checksums.txt

Needs cosign. The identity pattern is the one the installer itself uses.

cosign verify-blob
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/checksums.txt
curl -LO https://github.com/glincker/levelrail/releases/download/v1.5.6/checksums.txt.sigstore.json
cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

3. Container image

Checked against the v1.5.6 digest from the release notes. Images also carry an SBOM and provenance.

cosign verify
cosign verify ghcr.io/glincker/levelrail@sha256:6599832a52516db9f036d30bfa3d6321eaa3452885a1510d38c9ccc845a22c1d \
  --certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Release files: checksums.txt, checksums.txt.sigstore.json. More in the signature docs.

After installing: check that it worked

The installer already fails loudly if the control plane is not healthy within 60 seconds. You can re-check at any time.

  • Health check answers

    curl -fsS http://127.0.0.1:8080/healthz
  • Setup status is true until the first admin exists

    curl -fsS http://127.0.0.1:8080/api/v1/auth/setup-status
  • The service is active

    systemctl status levelrail
  • Back up the master key in /var/lib/levelrail-data. Every stored secret is encrypted with it.

Versions and channels

Pin a version or follow the beta channel

The latest tag follows stable releases. Use an exact tag to stay on one release, or the beta tag to follow pre-releases.

Pin to v1.5.6

pinned image
docker pull ghcr.io/glincker/levelrail:v1.5.6

Beta channel

beta channel
docker pull ghcr.io/glincker/levelrail:beta

Beta follows the newest pre-release. Use it for testing, not for the server your team depends on.

Stay current

Upgrade an existing install

Replaces the binary and restarts the service, keeping the unit file and your data. The previous binary is kept for rollback.

From the CLI or dashboard

check, then apply
levelrail-cli upgrade
levelrail-cli upgrade --apply

Runs read-only preflight checks first and rolls back automatically if the new release is not healthy within 90 seconds. The same flow is in Settings, Updates. Upgrade docs

Remove

Uninstall

Removal keeps your data unless you delete the data directory yourself.

Steps for removing the service are in the install instructions on GitHub. Removal does not touch Docker, the containers, images and volumes of your deployed apps, or levelrail-cli.

Network and service

Firewall ports and the systemd service

PortDirectionUsed for
80/tcpInboundHTTP, and the Let's Encrypt HTTP-01 challenge. Never moved by the installer on its own.
443/tcpInboundHTTPS for the dashboard and your apps.
443/udpOptionalHTTP/3.
8080/tcpDashboard and APIThe first-run setup link. Plain HTTP. If something else holds 8080 the installer picks the next free port and prints it.
NoneAgent-only nodesAgents dial out to the control plane, so they need no inbound ports.

Open the ports

ufw
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp

Or use your cloud provider's security group. Set LEVELRAIL_CONFIGURE_UFW=1 on the installer to have it add the rules.

The systemd service

service
sudo systemctl status levelrail
sudo systemctl restart levelrail
sudo journalctl -u levelrail -n 50

The installer writes the unit plus a drop-in at /etc/systemd/system/levelrail.service.d/10-install.conf holding your ports. Upgrades read it back and do not rewrite it.

What the installer does

The installer is open source and ships as a release asset on GitHub. Read it there before you run anything.

  1. Runs preflight checks (root, architecture, OS, systemd, curl, Docker version, RAM, free disk, ports 80, 443 and 8080). Low RAM only warns, other failed checks stop the install unless you pass --force. If ports 80 or 443 are already held by another service, it switches to coexist mode (ingress on 8088 and 8443, dashboard on loopback) instead of failing.
  2. Installs Docker if it is missing.
  3. Downloads the newest stable release for your architecture, verifies its SHA-256 checksum and, when cosign is available, its cosign signature. It installs a pinned cosign if none is present, unless you pass --no-cosign.
  4. Installs levelrail-cli to /usr/local/bin from the same release.
  5. Writes a systemd unit, starts it and waits for the health check.
  6. Checks that ports 80 and 443 answer on the public IP and prints the firewall commands if they do not.
  7. Prints the dashboard URL, a one-time setup token for the first admin, and a reminder to back up the master key in /var/lib/levelrail-data.

Troubleshooting

Preflight checks fail and the install stops

The host is missing something the installer needs: Docker 24 or newer, free ports 80 and 443, 1 GB RAM or 10 GB free disk. Fix the one that failed and run the installer again. The install instructions on GitHub list the options for taken ports.

systemctl status levelrail
The control plane starts but does not answer

Another process may hold the port, or the service failed to bind. Read the unit status and the last journal lines, and check which process owns 8080 or the port you set with LEVELRAIL_DASHBOARD_PORT. Restart the service once it is fixed.

sudo systemctl status levelrail
sudo journalctl -u levelrail -n 50
The dashboard or CLI says Docker is unreachable

Docker may not be running or its socket is not at /var/run/docker.sock. Confirm Docker itself works, then see the full error from levelrail-cli. Start Docker with systemctl, or set DOCKER_HOST for a non-standard socket.

sudo docker ps
levelrail-cli status --json
The setup link does not work or the token expired

The setup token is single-use and valid for 15 minutes, and the dashboard port may differ from the default. Print a new token on the server, then open the login page with it.

sudo APP_DATA_DIR=/var/lib/levelrail-data levelrail setup-token

More cases are in the troubleshooting docs.

Install questions

How do I install Levelrail?

Pull the image with docker pull ghcr.io/glincker/levelrail:latest on a Linux server with Docker, or download a release from GitHub. The install instructions are in the README on GitHub.

What are the requirements to install Levelrail?

A Linux server (amd64 or arm64) with systemd, root access, curl and ports 80 and 443 open. 1 vCPU, 1 GB RAM and 10 GB disk is a starting point. Ubuntu 24.04 and Debian 12 are tested in CI.

Does Levelrail run on Windows or macOS?

No. Nodes must be Linux. You can still control a server from any machine with the CLI or the dashboard.

How do I uninstall Levelrail?

Follow the uninstall steps in the install instructions on GitHub. Your data is kept unless you delete the data directory yourself. Docker and the containers and volumes of your deployed apps are not removed.

Ready when your server is

Pull the image or download a release from GitHub. Then deploy your first app.

docker pull ghcr.io/glincker/levelrail:latest