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.
Install
For a Linux server you own. Pull the image, or download a release from GitHub.
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.
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
The path
Four steps, about five minutes. These are real screens from a fresh install.
Step 1
Pull the image and run it on a Linux host with Docker, or download a release from GitHub.
$ docker pull ghcr.io/glincker/levelrail:v1.5.6 Step 2
The summary prints the dashboard URL and a one-time token. Valid for 15 minutes, print a new one any time.
$ sudo APP_DATA_DIR=/var/lib/levelrail-data levelrail setup-token Step 3
Open the setup link, paste the token and pick a username and password.
Step 4
The sample app goes healthy with an automatic address. Then enable HTTPS from Domains.
Before you start
OS
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
24 or newer. The installer sets it up through get.docker.com if it is missing.
Access
Root on the host.
Ports on the control plane node
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
None. Agents dial out to the control plane.
Starting size
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
Every file below is from the v1.5.6 release on GitHub. Verify the checksum before you run a binary.
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.
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 Also for 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.
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 Also for linux arm64
Multi-arch images for linux/amd64 and linux/arm64, signed with cosign. Pin the exact tag for anything you care about staying still.
docker pull ghcr.io/glincker/levelrail:v1.5.6
docker pull ghcr.io/glincker/levelrail-agent:v1.5.6 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.
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.
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-cliOr download the binary yourself:
Verify
Every release file is listed in checksums.txt, and checksums.txt itself is signed with cosign keyless signing from this repository's release workflow.
Run it in the folder with the file and checksums.txt. It skips files you did not download.
sha256sum --ignore-missing -c checksums.txt 9179101c32baa573c150dd9cbacb559983d37d14727c1365c60836baf018ce6f levelrail-linux-amd64bc17a8dbf76898c1c051cf2f594e9aa5e745e9e057275a78949ded23811eb551 levelrail-linux-arm64 Needs cosign. The identity pattern is the one the installer itself uses.
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 Checked against the v1.5.6 digest from the release notes. Images also carry an SBOM and provenance.
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.
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
The latest tag follows stable releases. Use an exact tag to stay on one release, or the beta tag to follow pre-releases.
docker pull ghcr.io/glincker/levelrail:v1.5.6 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
Replaces the binary and restarts the service, keeping the unit file and your data. The previous binary is kept for rollback.
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
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
| Port | Direction | Used for |
|---|---|---|
80/tcp | Inbound | HTTP, and the Let's Encrypt HTTP-01 challenge. Never moved by the installer on its own. |
443/tcp | Inbound | HTTPS for the dashboard and your apps. |
443/udp | Optional | HTTP/3. |
8080/tcp | Dashboard and API | The first-run setup link. Plain HTTP. If something else holds 8080 the installer picks the next free port and prints it. |
None | Agent-only nodes | Agents dial out to the control plane, so they need no inbound ports. |
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.
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.
The installer is open source and ships as a release asset on GitHub. Read it there before you run anything.
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 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 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 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.
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.
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.
No. Nodes must be Linux. You can still control a server from any machine with the CLI or the dashboard.
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.
Pull the image or download a release from GitHub. Then deploy your first app.
docker pull ghcr.io/glincker/levelrail:latest