bty-lab server setup¶

The network-flash flow needs a long-running bty-web container on a Linux host: it serves the browser UI, the per-MAC PXE plans, the iPXE bootfile, and proxies image bytes through a withcache sidecar. bty-lab deploy writes the compose stack, brings it up, and (when run as root) installs Podman Quadlet units so the stack auto-starts on boot.

Prerequisites¶

You need	Notes
A Linux host with root + `podman`	A small lab box or a VM is fine. Stack idles at ~150 MiB RAM.
`pipx` (or `uvx`)	To run `bty-lab` without a global pip install.
A LAN DHCP server	bty runs no DHCP role; the operator’s existing DHCP is the prerequisite for PXE clients to find the bty host (see bty via netboot for DHCP wiring).

Step 1: Pick a storage mode¶

The deploy keeps all mutable state under one parent path (default ./data next to compose.yml). The path defaults work for most hosts; for larger fleets put state on a dedicated drive so it survives an OS reflash.

Mode A: single disk (everything on the system disk)¶

Nothing to do here. Skip to Step 2; the default --data-dir puts state next to compose.yml.

Mode B: dedicated drive for bty state¶

# Pick the target drive (must be empty); replace /dev/sdX.
lsblk -o NAME,SIZE,MODEL,SERIAL,FSTYPE,MOUNTPOINT
sudo wipefs -a /dev/sdX
sudo mkfs.ext4 -L bty-data /dev/sdX

# Mount it at /srv/bty.
sudo mkdir -p /srv/bty
UUID=$(sudo blkid -o value -s UUID /dev/sdX)
echo "UUID=$UUID  /srv/bty  ext4  defaults,noatime,nofail  0 2" | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount -a
df -h /srv/bty

/srv/bty will hold both bty/ (state.db, backups, netboot artifacts) and withcache/ (cached image blobs) – one drive, one mount, one path to back up.

Step 2: Deploy¶

# Mode A: default ./data next to compose.yml
sudo uvx bty-lab deploy /opt/bty

# Mode B: state on the dedicated drive
sudo uvx bty-lab deploy /opt/bty --data-dir /srv/bty

deploy writes compose.yml + envvars under /opt/bty/, installs Podman Quadlet units to /etc/containers/systemd/, and starts the services via systemctl. Stack survives host reboots.

End-of-deploy output points at the two URLs:

bty:       http://<host>:8080/ui     (login: bty-lab / bty-lab)
withcache: http://<host>:3000/       (login: bty-lab / bty-lab)

Change the passwords in /opt/bty/envvars before exposing past a trusted LAN.

Step 3: Verify¶

curl -fsS http://localhost:8080/healthz   # bty-web up
sudo systemctl status bty-web withcache    # systemd green

Open http://<host>:8080/ui in a browser, log in with bty-lab / bty-lab. The dashboard shows machine + image counts (both zero on a fresh deploy).

Step 4: Load the default catalog¶

From the Images page click Fetch latest catalog. That pulls nosi’s published catalog (rolling oras tags for the bty + nosi images) into bty-web’s catalog_entries. PXE clients will then see the same image list the USB flow exposes.

Day 2¶

Task	Command
Upgrade in place	`sudo uvx bty-lab upgrade /opt/bty`
Back up state	The `/ui/backups` page (or `bty-web export` for a portable bundle)
Move to a new host	`bty-web export` + `bty-web import` – see Operations
Inspect raw files	`ls /opt/bty/data/` (Mode A) or `ls /srv/bty/` (Mode B)