Install

One line on Ubuntu. One compose file anywhere else.

Three ways in, and one fact about your host picks it. The shell installer wants Ubuntu 24.04 or 26.04 and the ISO brings its own; Docker runs on any distribution, which is also the answer on Ubuntu 26.04 — resolute ships Python 3.14 and does not package Guacamole, so the native install has nothing to build against. No signup, no key, nothing to register.

Pick your host

Whichever you pick: the RDMA lab alone wants Linux 7.1+ on the host, where rdma_rxe gained its per-namespace UDP 4791 socket. Below that it starts and moves no data, and says so on first run. Detail and the check.

On 26.04 there is no RDP console. Ubuntu stopped packaging Guacamole after 24.04, so Labtris builds guacd from source there, and 1.6.0 does not compile against FreeRDP 3 — the only FreeRDP 26.04 ships. VNC, SSH and telnet consoles all work, and QEMU consoles are VNC. It only bites if you connect to a Windows guest over RDP, in which case use 24.04 or the compose install, which pulls a prebuilt guacd with RDP in it.

On a fresh Ubuntu 24.04 or 26.04 host

Runs about five minutes and finishes with the URL to open, where the config lives, and where the generated database password sits. Idempotent — re-run to upgrade.

curl -fsSL https://labtris.com/install | sudo bash

From a fork

The installer clones https://github.com/labtris/labtris. To install your own fork, set LABTRIS_REPO; if the fork is private, also set LABTRIS_TOKEN, which is sent as a header on the clone and written nowhere on the host.

What it does

Refuses to run on anything but Ubuntu 24.04 or 26.04 x86_64 (override with LABTRIS_FORCE_OS=1).
Installs git, curl, ca-certificates.
Clones the repository to /opt/labtris, using the token for that one request.
Hands off to packaging/install-labtris.sh, which sets up Postgres, the service user, systemd units, nginx, everything.
Prints a summary block and writes /root/labtris-install-summary.txt.

Read the script first — recommended

Piping a shell script into sudo bash is a trust exercise. The installer at /install is get.sh from the repository, served here unchanged — kept tiny and readable on purpose. The real installer, packaging/install-labtris.sh, is in the clone it makes; read it there before the hand-off if you want to.

View the script

One compose file, any Linux host

No distribution requirement at all. Verified on Ubuntu 24.04 and 26.04; Debian, RHEL, Arch, Alpine and anything else with a working Docker are expected to be fine but are not ones we run. Only the RDMA lab cares what is underneath, and only about the kernel version, not the distribution. Docker and a working /dev/kvm are the only two things it asks for. Nothing is cloned — the compose file is served from this site and the image from GitHub’s registry — and upgrading is a tag bump rather than a reinstall.

curl -fsSL https://labtris.com/compose | docker compose -f - up -d

What you get

Every Labtris process shares one private container namespace, so lab bridges, taps and nftables rules land there — the host’s own networking is untouched.
Container nodes run on a private Docker daemon, not the host’s socket.
Ports publish on 127.0.0.1 by default; widen with LABTRIS_BIND once you have an admin account.
Two things it can’t do, because of that isolation: cloud networks that put a lab on a physical segment, and the settings that rewrite the host’s netplan.

Not a laptop path

Docker Desktop on macOS and Windows is unsupported — there is no /dev/kvm to hand it, and the container would be sharing a namespace inside Docker’s own Linux VM rather than your machine. Run a Linux VM instead.

Docker reference →

Bootable ISO for bare metal or air-gapped

Every Debian package, every Python wheel and the built interface baked in — nothing fetched during install. 3.8 GB as of 0.12.0, so GitHub’s 2 GiB asset cap splits it in two. BIOS and UEFI both boot from the same image.

# the two parts and the checksum, from https://github.com/labtris/labtris/releases/latest
cat labtris-0.13.13-amd64.iso.part-* > labtris-0.13.13-amd64.iso
sha256sum -c labtris-0.13.13-amd64.sha256

What you get on first boot

Five AI-fabric labs are already on the canvas: a UET pair, an RDMA pair, a bmv2 switch running the UEC packet-trimming program, a link with eight priority classes, and a two-spine two-leaf fabric with four Ultra Ethernet endpoints. They arrive wired, and every image they need pulls from a registry — ghcr.io/labtris/uet-ref and ghcr.io/labtris/rdma-host are published by CI, the rest come from Docker Hub. Nothing to build first.

One caveat, and it is the ISO’s alone: this image installs Ubuntu 24.04, whose kernel is older than the 7.1 that soft-RoCE needs. Four of the five labs run as shipped. The RDMA pair does not transfer until you put a newer kernel on the machine — it comes up, the devices appear, and the bytes never move. The lab says so itself on first run rather than leaving you to find it. The other two install routes let you pick the kernel; this one does not, which is why it is called out here.

All images are linux/amd64. On an arm64 machine docker pull fails with “no matching manifest for linux/arm64/v8”; add --platform linux/amd64 to inspect one. Labtris itself needs a Linux host with KVM, so arm64 would mean the whole set, not just a node image — say so if you need it.

Booting it

Attach the .iso to a VM and boot — Proxmox, ESXi, VMware, Hyper-V, VirtualBox or QEMU. Give it 6+ vCPU, 12 GB RAM and 60 GB of disk, and enable nested virtualisation if you want QEMU nodes inside it to run at useful speed. The install is unattended and takes six to ten minutes.

For bare metal, write it to a USB stick with Etcher or, on Windows, Rufus — both give you a device picker.

When this is the right one

A machine with no route out, or when bare-metal provisioning is the whole point. Verify the checksum before writing — a truncated part produces an ISO that boots and then fails halfway through the install.

Download the ISO →

Upgrading

One command, with a backup taken first.

Goes to the latest release, dumps the database before it migrates anything, and tells you whether the result is actually serving. Your labs, pods, images and database are carried across, not replaced.

curl -fsSL https://labtris.com/upgrade | sudo bash

A specific release instead: … | sudo bash -s -- --to v0.12.0. To see what it would do and change nothing: … | sudo bash -s -- --check. The -s -- matters — without it bash takes the flags for itself rather than passing them on.

Compose install

The command above is for the native install. With the compose file, the image is the release, so upgrading is pulling a newer one. Back up the database first; the api container migrates it on start and a migration cannot be undone.

docker compose exec postgres pg_dump -U labtris labtris > labtris-$(date +%F).sql
docker compose pull
docker compose up -d

Labs, images and pods live in named volumes (postgres-data, labtris-state, labtris-images, dind-storage), not in the image, so a new image finds them where the old one left them. Container nodes keep running through the upgrade. VMs stop with the old api, because it is their parent process, and the new one starts again every node that was running, four at a time; set LABTRIS_RESTORE_RUNNING_NODES=false to leave them stopped instead. The first upgrade onto a compose file from before October 2026 restarts container nodes once too. To pin a release instead of latest, set LABTRIS_IMAGE=ghcr.io/labtris/labtris:v0.13.12 in .env next to the compose file; to roll back, set the old tag and run docker compose up -d.

What it does, in order

Resolves the newest release tag from the GitHub API, because a --depth 1 clone has no tags locally and sorting them as text puts v0.9.0 above v0.12.0. Then pg_dump to /var/backups/labtris — always, with no flag to skip, because alembic upgrade head is not reversible. Then fetch, check out, reinstall dependencies, migrate, restart. Then it verifies labtris-api and labtris-netd are active and the interface answers, and on failure prints the journal command, the previous commit and the path to the dump.

Verified on a real 0.11.0 install: upgraded to 0.12.0 with its two existing labs still present afterwards, and a restorable 7.5 KB dump on disk.

Docker installs do not use this

A compose deployment is a tag bump. From the directory holding your compose file:

docker compose pull && docker compose up -d

Volumes are untouched, and the API container runs the same migrations on start.

After install

Where to look when something breaks.

	Shell installer or ISO	Docker
Web UI	https://<host>/ (also :8081, plain HTTP)	http://<host>:8080
Config	/etc/labtris/labtris.env	environment: in docker-compose.yml
DB password	/etc/labtris/db-password	set in docker-compose.yml
Health check	labtris system doctor	docker compose exec api labtris system doctor
Logs	journalctl -u labtris-api -u labtris-netd -f	docker compose logs -f api netd
Restart	systemctl restart labtris-api labtris-netd	docker compose restart

The full handbook lives at docs.labtris.com.