Install

For a Linux server you own. The installer always picks the newest stable release, and sets up Docker if it is missing.

  • 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.4.0
  • v1.4.0 Kubernetes clusters, cloud providers and the Integrations hub (a4068f0)
Full release notes
root@your-server
curl -fsSL https://levelrail.com/install.sh | sudo sh# Checks the host and installs Docker if it is missing# Installs the control plane and starts it as a systemd service# Prints the dashboard URL and a one-time setup token

Run it as root on the server. Then open the setup link it prints. Prefer to read it first? install.sh at v1.4.0

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

    Run the installer

    One command as root. It checks the host and installs Docker if needed.

  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.

Check the server first. A read-only readiness report that changes nothing and runs without root: curl -fsSL https://levelrail.com/install.sh | sh -s -- --check

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, plus curl.

  • 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.4.0 release on GitHub. The one-line installer does all of this for you, including checksum and signature checks. Use these when you want the files yourself.

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.4.0/levelrail-linux-amd64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/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.4.0

534cf5bbc3206a54a48f048464a7a792f32fe3358802681e94d4b2fc955f1b1e  levelrail-linux-amd64

Linux arm64

levelrail-linux-arm64Control plane, 342 MB
  • ARM64 (aarch64)
  • 342 MB
  • v1.4.0

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.4.0/levelrail-linux-arm64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/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.4.0

16d2b75126403a2901f5e31712ec8d166ebc42cde4a9ad06fb3c9bb679b037f4  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. The installer remains the recommended path for a real single-node server because it also provisions Docker and a systemd unit.

pull
docker pull ghcr.io/glincker/levelrail:v1.4.0
docker pull ghcr.io/glincker/levelrail-agent:v1.4.0
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.4.0

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. The server installer sets up the server, not a remote client.

curl -fsSL https://levelrail.com/install-cli.sh | sh

On macOS and Linux it detects your architecture, checks the checksum and installs to ~/.local/bin, or /usr/local/bin with sudo. Or download the binary yourself:

  • macOS amd64levelrail-cli-darwin-amd64, 149 MB Download
  • macOS arm64levelrail-cli-darwin-arm64, 140 MB Download
  • Linux amd64levelrail-cli-linux-amd64, 145 MB Download
  • Linux arm64levelrail-cli-linux-arm64, 134 MB Download
  • Windows amd64levelrail-cli-windows-amd64.exe, 144 MB Download
  • Windows arm64levelrail-cli-windows-arm64.exe, 133 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
534cf5bbc3206a54a48f048464a7a792f32fe3358802681e94d4b2fc955f1b1e  levelrail-linux-amd64
16d2b75126403a2901f5e31712ec8d166ebc42cde4a9ad06fb3c9bb679b037f4  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.4.0/checksums.txt
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/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.4.0 digest from the release notes. Images also carry an SBOM and provenance.

cosign verify
cosign verify ghcr.io/glincker/levelrail@sha256:328f2a1a5ad505173c1182df00d7253d93a033d160a63eed56478dcd71e9cb1f \
  --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

By default the installer picks the newest stable release. Set LEVELRAIL_VERSION to install an exact tag, or LEVELRAIL_CHANNEL=beta to follow pre-releases.

Pin to v1.4.0

pinned install
curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_VERSION=v1.4.0 sh

Beta channel

beta channel
curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_CHANNEL=beta sh

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.

With the installer

upgrade to the newest
curl -fsSL https://levelrail.com/install.sh | sudo sh -s upgrade
upgrade to v1.4.0
curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_VERSION=v1.4.0 sh -s upgrade

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

Removes the service, unit file and binary, and keeps your data.

uninstall
curl -fsSL https://levelrail.com/install.sh | sudo sh -s uninstall
uninstall and purge
curl -fsSL https://levelrail.com/install.sh | sudo sh -s uninstall --purge

--purge also deletes the data directory: the database, the master key and certificates. That removes all app and deploy state and the key your secrets are encrypted with.

Neither command removes 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

You are piping a script into a root shell, so here is exactly what it does. The script is open source and you can read it first.

  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. Run the read-only check (no root needed) to see which one failed, fix it and run the installer again. Pass --force to continue past a failed check, or set LEVELRAIL_COEXIST=1 if the ports are taken.

curl -fsSL https://levelrail.com/install.sh | sh -s -- --check
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?

Run curl -fsSL https://levelrail.com/install.sh | sudo sh on a Linux server with systemd. It checks the host, installs Docker if needed, installs the control plane and prints a one-time setup link for the first admin.

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?

Run the installer with the uninstall argument. It removes the service, unit file and binary and keeps your data unless you add --purge. It does not remove Docker or the containers and volumes of your deployed apps.

Ready when your server is

One command installs the control plane. Then deploy your first app.

curl -fsSL https://levelrail.com/install.sh | sudo sh