Install with Docker Compose

Install the hub from the release files with your own docker compose commands instead of the install script. You run the same pinned images and get the same stack.

What you'll need

Docker Engine and Docker Compose 2.33.1 or newer. Confirm with docker compose version.
curl and sha256sum. On macOS, use shasum -a 256 in place of sha256sum.
About 700 MB of free disk for the images. The first start downloads about 265 MB of them.
Optional: GitHub CLI (gh), signed in with gh auth login, to check signed provenance.

1. Download the release files

Every Hub release publishes four files:

File	What it is
`docker-compose.deploy.yml`	The stack, with every image pinned by digest
`deploy.env.example`	Settings for the stack: image, ports, bind addresses, TLS mode
`deploy-manifest.json`	The release version and its image digests
`SHA256SUMS`	SHA-256 checksums of the three files above

Download them into a new, empty directory. The directory name becomes the Compose project name, so labtether gives volumes such as labtether_postgres-data, the same names the install script uses.

mkdir labtether && cd labtether
VERSION=v1.7.1
URL=https://github.com/labtether/labtether/releases/download/$VERSION
for f in docker-compose.deploy.yml deploy.env.example \
         deploy-manifest.json SHA256SUMS; do
  curl --proto '=https' --tlsv1.2 -fsSLO "$URL/$f"
done

Use the newest tag from GitHub Releases in place of v1.7.1.

2. Check the files

sha256sum --check SHA256SUMS

All three lines must end in OK. If one says FAILED, delete the directory and download again.

SHA256SUMS comes from the same release as the files it checks, so it proves the download is complete and unchanged. To also check that GitHub's release workflow built the files from the release tag, verify their signed provenance:

for f in docker-compose.deploy.yml deploy.env.example \
         deploy-manifest.json SHA256SUMS; do
  gh attestation verify "$f" --repo labtether/labtether \
    --signer-workflow labtether/labtether/.github/workflows/release.yml \
    --source-ref "refs/tags/$VERSION" --deny-self-hosted-runners
done

Each file prints ✓ Verification succeeded!. A changed file prints an error instead. The install script runs the same two checks.

3. Read the Compose file

Open docker-compose.deploy.yml before you start it. It defines these services:

Service	What it does	Port on the host
`labtether-bootstrap`	Runs once, creates the database password and setup token in its volumes, then exits	none
`postgres`	PostgreSQL 18 for the hub	none
`labtether`	The hub API, agent connections and background jobs	`127.0.0.1:8080` (HTTP), `127.0.0.1:8443` (HTTPS)
`web-console`	The web console	none
`console-ingress`	Forwards port 3000 to the web console	`127.0.0.1:3000`
`guacd`	RDP gateway, off unless you turn on the `remote-desktop` profile	none

The hub, web console and ingress run as user 65532 with a read-only root filesystem and every Linux capability dropped. labtether-bootstrap runs as root to set file owners in the volumes. It and postgres drop every capability except the few they need for that, and postgres also keeps the two it needs to switch to its own user. Each service has memory and CPU limits under deploy.resources.limits.

4. Create the settings file

install -m 600 deploy.env.example .env.deploy

The defaults work as they are. Every port binds to 127.0.0.1, so the console opens only on the Docker host. To change that, edit .env.deploy now or later; Installation explains the bind settings. Leave LABTETHER_IMAGE alone: it must match the digest in deploy-manifest.json.

5. Start the hub

docker compose --env-file .env.deploy -f docker-compose.deploy.yml up -d

The first start pulls the images, runs labtether-bootstrap, then waits for the hub to report healthy before it starts the web console. Check that everything came up:

docker compose --env-file .env.deploy -f docker-compose.deploy.yml ps --all

postgres, labtether, web-console and console-ingress show healthy. labtether-bootstrap shows Exited (0).

6. Create the owner account

Print the one-time setup token on the Docker host:

docker compose --env-file .env.deploy -f docker-compose.deploy.yml exec -T labtether sh -c 'cat /bootstrap/auth/setup-token'

Open http://localhost:3000, paste the token and choose the owner's username and password. The token works only until the first account exists. First Login covers the rest of the setup wizard.

Keep the directory

Run every later docker compose command from this directory with the same --env-file .env.deploy -f docker-compose.deploy.yml flags. Keep the four release files: you need them to roll back after an upgrade.

Upgrade: download the new release's files into an empty directory, check them, then copy docker-compose.deploy.yml and deploy-manifest.json over the old ones. See Upgrading.
Back up: see Backup and restore.
Remove: see Uninstall.

Install with Docker Compose#

What you'll need#

1. Download the release files#

2. Check the files#

3. Read the Compose file#

4. Create the settings file#

5. Start the hub#

6. Create the owner account#

Keep the directory#