Docs / Self-hosting
Run the backend in a container
Run the backend, which tracks runs, claims, messages and the dashboard across your machines, with Docker Compose or rootless Podman Quadlet. This setup is a preview.
Preview. The container recipes are not a claim of tested production support. CI builds the image on Linux amd64 and arm64 and exercises health, node authentication, event ingestion, crash retention, SQLite online backup and restore, and HTTPS enrollment through a loopback proxy. CI does not run the Compose or Quadlet files. The Podman Quadlet recipe is still a proposal that awaits operator acceptance.
This guide runs the backend from a versioned, non-root image. The backend tracks runs, claims and messages across your machines and serves the dashboard, and the commands call it Fleet Hub. The recorded image is the Python-only hub and does not include shared memory. It has two recipes: Docker Compose, and a rootless Podman Quadlet that systemd runs for you. For what the hub does and when to use one, read Run the backend. Prefer a dedicated container on Proxmox? Use the Proxmox LXC guide instead.
Set up with your agent
Recorded baseline
The image installs Brigade from reviewed source commit e6009f6969dc6e45db2ab93790aa3e407c791409 (CLI version 0.28.0) on python:3.12.14-slim-bookworm (Debian 12). That ref includes the loopback proxy trust option. Released 0.27.0 does not. CI prints the OS, architecture, Python, OpenSSL and SQLite versions of each built image and requires OpenSSL 3.0.20 or newer. Debian’s DSA-6015-1 marks Bookworm’s 3.0.20 package as fixed, and the pinned image reports 3.0.20. A Linux amd64 smoke run on 2026-10-13 reported Debian GNU/Linux 12 (bookworm), x86_64, Python 3.12.14, OpenSSL 3.0.20 and SQLite 3.40.1.
For a local image, record its immutable manifest digest before you deploy:
podman image inspect --format '{{.Digest}}' localhost/brigade-fleet-hub:0.28.0-e6009f6
podman run --rm --entrypoint python localhost/brigade-fleet-hub:0.28.0-e6009f6 \
-c 'import platform,sqlite3,sys; print(platform.platform()); print(sys.version); print(sqlite3.sqlite_version)'
Deploy the recorded localhost/brigade-fleet-hub@sha256:<REVIEWED_DIGEST>, never a mutable tag. Brigade does not publish this image to a registry, so you build it yourself.
This baseline predates schema 32, T3 lifecycle intake, and per-seat native T3 launch models. Use a separately reviewed newer image before you turn those features on. The smoke results above do not cover them.
Before you start
Run every command from a checkout of the Brigade repository. The files below live in ops/fleet-hub/. Paths such as ops/fleet-hub/Containerfile are relative to the repository root.
compose.yamlbuilds and runs the hub for Docker Compose.Containerfilebuilds the image for both recipes.quadlet/brigade-fleet.containerandquadlet/brigade-fleet.volumeare the Podman units.
The compose.yaml and Containerfile quoted next are the older single-service baseline that the recorded e6009f6 image was built from. They are not the files in the 0.31.0 repository. What 0.31.0 ships lists the differences, and the Docker Compose section says which steps still apply.
compose.yaml (older baseline)
services:
hub:
build:
context: ../..
dockerfile: ops/fleet-hub/Containerfile
args:
BRIGADE_REF: e6009f6969dc6e45db2ab93790aa3e407c791409
image: localhost/brigade-fleet-hub:0.28.0-e6009f6
restart: unless-stopped
init: true
ports:
- "127.0.0.1:3774:3774"
secrets:
- source: admin_token
target: admin_token
volumes:
- brigade-state:/var/lib/brigade
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3774/health', timeout=2).read()"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
secrets:
admin_token:
file: ./secrets/admin-token.txt
volumes:
brigade-state:
Containerfile (older baseline)
FROM python:3.12.14-slim-bookworm@sha256:392307d22300de8b5986851a12d9176dfc0fc073e65bf6523ebd7dcbeb23564e
ARG BRIGADE_REF=e6009f6969dc6e45db2ab93790aa3e407c791409
ARG BRIGADE_SHA256=68014a8e99c61f5e547d8bf223a5f3ad7ea31f60355a4c30356bffd78e15c168
LABEL org.opencontainers.image.source="https://github.com/escoffier-labs/brigade" \
org.opencontainers.image.version="0.28.0" \
org.opencontainers.image.revision="${BRIGADE_REF}" \
org.opencontainers.image.description="Brigade Fleet Hub"
RUN python -m pip install --no-cache-dir setuptools==75.8.0 wheel==0.45.1 \
&& python -c "import hashlib, urllib.request; data = urllib.request.urlopen('https://github.com/escoffier-labs/brigade/archive/${BRIGADE_REF}.tar.gz').read(); assert hashlib.sha256(data).hexdigest() == '${BRIGADE_SHA256}', 'Brigade source archive checksum mismatch'; open('/tmp/brigade.tar.gz', 'wb').write(data)" \
&& python -m pip install --no-cache-dir --no-build-isolation /tmp/brigade.tar.gz \
&& rm /tmp/brigade.tar.gz \
&& groupadd --gid 10001 brigade \
&& useradd --uid 10001 --gid 10001 --no-create-home --home-dir /var/lib/brigade brigade \
&& install -d -o 10001 -g 10001 -m 0700 /var/lib/brigade
USER 10001:10001
VOLUME ["/var/lib/brigade"]
EXPOSE 3774
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3774/health', timeout=2).read()"]
ENTRYPOINT ["brigade", "fleet", "serve"]
CMD ["--host", "0.0.0.0", "--port", "3774", "--db", "/var/lib/brigade/fleet-hub.db", "--token-file", "/run/secrets/admin_token"]
quadlet/brigade-fleet.container
[Unit]
Description=Brigade Fleet Hub
After=network-online.target
Wants=network-online.target
[Container]
Image=localhost/brigade-fleet-hub@REPLACE_WITH_RECORDED_DIGEST
Pull=never
ContainerName=brigade-fleet-hub
PublishPort=127.0.0.1:3774:3774
Volume=brigade-fleet.volume:/var/lib/brigade
Secret=brigade-fleet-admin-token,target=admin_token
HealthCmd=python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3774/health', timeout=2).read()"
HealthInterval=30s
HealthTimeout=3s
HealthRetries=3
HealthOnFailure=kill
Notify=healthy
[Service]
TimeoutStartSec=120
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
quadlet/brigade-fleet.volume
[Volume]
VolumeName=brigade-fleet-state
User=10001
Group=10001
What 0.31.0 ships in ops/fleet-hub
Read these files in the 0.31.0 tag of the Brigade repository. The Quadlet files above are unchanged. The other two differ from the baseline:
compose.yamluses a holder layout. Anetnsholder container owns the network namespace. Thehuband a Tailscalefrontcontainer join it, so no service publishes a port. The hub binds127.0.0.1:3774inside that namespace with--trust-forwarded-protoand--route-mode memory=native, and readsconfig/hub.toml. Two optional services, anembedder(profilegpu) and abackupjob (profilebackup), run only when you ask for them. It pinsBRIGADE_REFa7746b6da2eec257890674de30635ca5036a2115and version 0.31.0 by default.Containerfilehas four stages:source,hub-build,python-hubanddogfood.dogfoodadds the Rustbrigade-hubbinary, and Compose builds it. The default, last stage is the Python-only image that the Quadlet recipe uses. PassBRIGADE_REF,BRIGADE_SHA256andBRIGADE_VERSIONtogether, or the checksum check fails.bin/hub-setup.py initwrites.env,config/hub.tomland the secrets, and must run before the firstdocker compose up. The Brigade repository’sdocs/runbooks/fleet-hub-dogfood.mdcovers it.
Docker Compose
The steps below were written for the older single-service compose.yaml shown above: a published 127.0.0.1:3774 port, one hub service, and the 0.28.0-e6009f6 image tag. With the 0.31.0 compose.yaml, set up and start the backend with docs/runbooks/fleet-hub-dogfood.md instead of steps 2 and 3. The image pinning, backup and rollback steps still apply, with the health check run inside the hub container instead of from the host.
1. Check the Docker Engine version
Docker Engine 28.0.0 or newer is required for the localhost-only port publication below. Older releases can expose localhost-published ports to hosts on the same layer-2 network.
engine_version="$(docker version --format '{{.Server.Version}}')"
python3 -c 'import re,sys; m=re.fullmatch(r"(\d+)\.(\d+)\.(\d+)", sys.argv[1]); assert m and tuple(map(int, m.groups())) >= (28, 0, 0), f"Docker Engine 28.0.0 or newer is required, found {sys.argv[1]}"' "$engine_version"
2. Create the admin token
Generate a random token without putting it in a command argument, then protect the file. Compose file-backed secrets are read-only bind mounts, so the container’s non-root user must be able to read the source file. Keep the host directory private and make the file readable by the container’s UID. Other host users still cannot reach it, because they cannot enter the directory.
The secrets/ path is ignored by Git. Running git clean -xdf deletes ops/fleet-hub/secrets/, including tokens, image archives and database backups. Keep a protected copy outside the checkout before you clean it. See Docker Compose secrets.
cd ops/fleet-hub
install -d -m 0700 secrets
umask 077
generated_token="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" || exit 1
test -n "$generated_token" || { echo "Token generation returned an empty value" >&2; exit 1; }
printf '%s\n' "$generated_token" > secrets/admin-token.txt
unset generated_token
chmod 0444 secrets/admin-token.txt
3. Build, pin and start
Record the built image’s immutable local ID in an ignored Compose override. The base file uses a version tag for the build, so use the recorded ID for every start or recreation.
docker compose build --pull hub
image_id="$(docker image inspect --format '{{.Id}}' localhost/brigade-fleet-hub:0.28.0-e6009f6)"
case "$image_id" in sha256:*) ;; *) echo "Expected a sha256 image ID" >&2; exit 1 ;; esac
cat > secrets/compose.image-id.yaml <<EOF
services:
hub:
image: ${image_id}
EOF
docker compose -f compose.yaml -f secrets/compose.image-id.yaml up -d --no-build \
--wait --wait-timeout 120
curl --fail http://127.0.0.1:3774/health
The wait options need a Compose CLI that supports up --wait. Compose waits for the health check before it returns, and curl then checks the local endpoint. This start command is for the first deployment only. For an upgrade, use the sequence below.
If the hub is unhealthy
The health check reports an unhealthy container, but Docker restart policies apply only when a container exits. An unhealthy hub process can keep running. Read its logs, then restart the pinned service and wait for health:
docker compose -f compose.yaml -f secrets/compose.image-id.yaml logs --tail=100 hub
docker compose -f compose.yaml -f secrets/compose.image-id.yaml restart hub
deadline=$((SECONDS + 120))
while true; do
remaining=$((deadline - SECONDS))
if [ "$remaining" -le 0 ]; then
echo "Fleet Hub did not recover within 120 seconds after restart" >&2
exit 1
fi
if curl --fail --connect-timeout 2 --max-time "$remaining" http://127.0.0.1:3774/health; then
break
fi
remaining=$((deadline - SECONDS))
if [ "$remaining" -gt 0 ]; then
sleep "$((remaining < 2 ? remaining : 2))"
fi
done
Upgrade
The override pins the local Docker image ID and is ignored along with the token directory. Before you rebuild the versioned tag, save the current image. That keeps its bytes if the tag is retargeted or Docker prunes unused images:
previous_id="$(sed -n 's/^[[:space:]]*image: //p' secrets/compose.image-id.yaml)"
case "$previous_id" in sha256:*) ;; *) echo "Expected a sha256 image ID" >&2; exit 1 ;; esac
archive="secrets/brigade-fleet-hub-${previous_id#sha256:}.tar"
docker image save --output "$archive" "$previous_id"
chmod 0600 "$archive"
Then create an online database backup while the current hub is running, and stop it. Keep the backup with the image archive, mode 0600:
set -euo pipefail
backup_path="secrets/fleet-hub-pre-upgrade-$(date -u +%Y%m%dT%H%M%SZ).db"
docker compose -f compose.yaml -f secrets/compose.image-id.yaml exec -T --user 10001 hub \
python -c 'import sqlite3; source=sqlite3.connect("/var/lib/brigade/fleet-hub.db"); target=sqlite3.connect("/var/lib/brigade/fleet-hub-pre-upgrade.db"); source.backup(target); target.close(); source.close()'
docker cp "$(docker compose -f compose.yaml -f secrets/compose.image-id.yaml ps -q hub):/var/lib/brigade/fleet-hub-pre-upgrade.db" "$backup_path"
chmod 0600 "$backup_path"
docker compose -f compose.yaml -f secrets/compose.image-id.yaml exec -T hub \
rm /var/lib/brigade/fleet-hub-pre-upgrade.db
docker compose -f compose.yaml -f secrets/compose.image-id.yaml stop hub
After the backup succeeds and the service stops, rebuild the candidate, inspect it for its new ID, and replace the image value in secrets/compose.image-id.yaml. Start it with docker compose -f compose.yaml -f secrets/compose.image-id.yaml up -d --no-build --wait --wait-timeout 120. Starting it may migrate the database. Compose waits for the health check before it returns.
The named volume holds the database and its WAL and SHM sidecars. Keep it on a local filesystem, never NFS, SMB or a cloud-synced directory. Never add --volumes to down. This recipe runs one replica and has no support for a database shared over a network.
Roll back
Load the saved image and check that its ID matches before you restore the database with it. The override changes only after the restore succeeds. Set the three variables from your recorded archive name, image ID and backup file:
set -euo pipefail
# Set these from the recorded image archive name and ID.
archive="secrets/brigade-fleet-hub-REPLACE_WITH_RECORDED_IMAGE_ID.tar"
previous_id="sha256:REPLACE_WITH_RECORDED_IMAGE_ID"
backup_path="secrets/fleet-hub-pre-upgrade-REPLACE_WITH_TIMESTAMP.db"
docker image load --input "$archive"
restored_id="$(docker image inspect --format '{{.Id}}' "$previous_id")"
test "$restored_id" = "$previous_id"
docker compose -f compose.yaml -f secrets/compose.image-id.yaml stop hub
docker run --rm --pull never --user 0 \
--volumes-from "$(docker compose -f compose.yaml -f secrets/compose.image-id.yaml ps -aq hub)" \
--volume "$PWD/$backup_path:/restore/fleet-hub.db:ro" \
--entrypoint python "$previous_id" -c 'import os,shutil,sqlite3,tempfile
database="/var/lib/brigade/fleet-hub.db"
source="/restore/fleet-hub.db"
if not os.path.isfile(source) or os.path.getsize(source) == 0: raise SystemExit("Backup must be a nonempty regular file")
fd, staged = tempfile.mkstemp(prefix=".fleet-hub-restore-", dir=os.path.dirname(database))
os.close(fd)
try:
shutil.copyfile(source, staged)
source_connection=sqlite3.connect(staged)
target_connection=None
try:
result=source_connection.execute("PRAGMA integrity_check").fetchone()[0]
if result != "ok": raise RuntimeError(result)
target_connection=sqlite3.connect(database)
source_connection.backup(target_connection)
finally:
if target_connection is not None: target_connection.close()
source_connection.close()
os.chown(database, 10001, 10001)
finally:
if os.path.exists(staged): os.remove(staged)'
cat > secrets/compose.image-id.yaml <<EOF
services:
hub:
image: ${previous_id}
EOF
docker compose -f compose.yaml -f secrets/compose.image-id.yaml up -d --no-build \
--wait --wait-timeout 120
The restore checks a staged copy, then uses SQLite’s online backup API to write into the stopped hub database. If the copy fails before it finishes, SQLite rolls back the write to the destination and manages the WAL and SHM sidecars with the live database. See SQLite’s backup API failure behavior. Keep the archive and image ID next to the database backup.
To run the repository’s image, token, persistence, backup and restore, and HTTPS proxy acceptance check, run ./.venv/bin/python tests/fleet_hub_container_smoke.py from the repository root. It needs a running Docker daemon and builds the pinned package version first.
Rootless Podman Quadlet
Use a Podman release whose Quadlet generator supports HealthOnFailure=kill and Notify=healthy. With them, systemd waits for the health check before it reports startup success, up to 120 seconds. First deployment and rollback both use this gate.
Hub setup does not touch the Fleet client configuration of your own account. An admin-only client config sends the admin token for events and claims, and this hub rejects that with HTTP 403 because admin writes are off by default. Enroll the local client after the hub starts, as shown below.
Build and install
Build the pinned image locally and record its digest. The 0.31.0 Containerfile needs all three build arguments, because its defaults point at a newer ref. Keep an operator copy of the admin token in a private file, import that file as a Podman secret, render the Quadlet with the digest, and copy both units to ~/.config/containers/systemd/:
set -euo pipefail
podman build -f ops/fleet-hub/Containerfile \
--build-arg BRIGADE_REF=e6009f6969dc6e45db2ab93790aa3e407c791409 \
--build-arg BRIGADE_SHA256=68014a8e99c61f5e547d8bf223a5f3ad7ea31f60355a4c30356bffd78e15c168 \
--build-arg BRIGADE_VERSION=0.28.0 \
-t localhost/brigade-fleet-hub:0.28.0-e6009f6 .
image_digest="$(podman image inspect --format '{{.Digest}}' localhost/brigade-fleet-hub:0.28.0-e6009f6)"
case "$image_digest" in sha256:*) ;; *) echo "Expected a sha256 image digest" >&2; exit 1 ;; esac
umask 077
token_dir="$HOME/.local/share/brigade-fleet-hub"
install -d -m 0700 "$token_dir"
token_file="$token_dir/admin-token"
if podman secret inspect brigade-fleet-admin-token >/dev/null 2>&1; then
test -s "$token_file" || {
echo "Existing Podman secret needs its saved operator token file at $token_file" >&2
exit 1
}
elif [ -e "$token_file" ] || [ -L "$token_file" ]; then
echo "Token file exists without the Podman secret; inspect and reconcile this partial state before continuing" >&2
exit 1
else
generated_token="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" || exit 1
test -n "$generated_token" || { echo "Token generation returned an empty value" >&2; exit 1; }
printf '%s\n' "$generated_token" > "$token_file"
unset generated_token
chmod 0600 "$token_file"
podman secret create brigade-fleet-admin-token "$token_file" || {
echo "Could not create the Podman secret; no unit was installed" >&2
exit 1
}
fi
install -d ~/.config/containers/systemd
sed "s|REPLACE_WITH_RECORDED_DIGEST|${image_digest}|" \
ops/fleet-hub/quadlet/brigade-fleet.container \
> ~/.config/containers/systemd/brigade-fleet.container
chmod 0644 ~/.config/containers/systemd/brigade-fleet.container
install -m 0644 ops/fleet-hub/quadlet/brigade-fleet.volume \
~/.config/containers/systemd/
if [ "$(loginctl show-user "$USER" --property=Linger --value)" != yes ]; then
loginctl enable-linger "$USER" || {
echo "Could not enable lingering; ask the system administrator to enable it for $USER" >&2
exit 1
}
fi
test "$(loginctl show-user "$USER" --property=Linger --value)" = yes || {
echo "Lingering is required to keep the rootless Hub running after logout" >&2
exit 1
}
systemctl --user daemon-reload
systemctl --user restart brigade-fleet.service
curl --fail --max-time 5 http://127.0.0.1:3774/health
Enroll the local client
If the same account also runs Brigade work and is not enrolled yet, enroll its machine identity. The saved admin token is used for this one command only:
node_id="$(brigadestack node --machine --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["node_id"])')"
BRIGADE_FLEET_HUB_URL=http://127.0.0.1:3774 \
BRIGADE_FLEET_TOKEN="$(cat "$HOME/.local/share/brigade-fleet-hub/admin-token")" \
brigadestack fleet nodes add "$node_id"
Save the returned node token in a private file before you turn the client on. Then follow client enrollment to install it and set node_token_file, with http://127.0.0.1:3774 as the hub URL for this local hub. To keep admin CLI access, also set token_file = "~/.local/share/brigade-fleet-hub/admin-token" in that final [fleet] section. Keep your existing client settings when you merge the config.
Upgrade
Before you rebuild the versioned tag, archive the image the installed unit refers to. Podman’s image archive keeps the layers, history and tags, so loading it restores the original local image:
unit="$HOME/.config/containers/systemd/brigade-fleet.container"
previous_ref="$(sed -n 's/^Image=//p' "$unit")"
previous_digest="${previous_ref##*@}"
case "$previous_digest" in sha256:*) ;; *) echo "Expected a sha256 image digest" >&2; exit 1 ;; esac
previous_id="$(podman image inspect --format '{{.Id}}' "$previous_ref")"
archive_dir="$HOME/.local/share/brigade-fleet-hub/archives"
install -d -m 0700 "$archive_dir"
archive="$archive_dir/brigade-fleet-hub-${previous_digest#sha256:}.tar"
podman image save --format oci-archive --output "$archive" "$previous_ref"
image_id_file="${archive%.tar}.image-id"
printf '%s\n' "$previous_id" > "$image_id_file"
chmod 0600 "$archive" "$image_id_file"
Before you deploy a candidate that may migrate the database, take an online SQLite backup while the current hub runs. It is the restore point for the archived image, because that image may refuse the candidate’s newer schema. Keep it with the image archive, mode 0600:
set -euo pipefail
backup_dir="$HOME/.local/share/brigade-fleet-hub/backups"
install -d -m 0700 "$backup_dir"
backup_path="$backup_dir/fleet-hub-pre-upgrade-$(date -u +%Y%m%dT%H%M%SZ).db"
podman exec brigade-fleet-hub python -c 'import sqlite3; source=sqlite3.connect("/var/lib/brigade/fleet-hub.db"); target=sqlite3.connect("/var/lib/brigade/fleet-hub-pre-upgrade.db"); source.backup(target); target.close(); source.close()'
podman cp brigade-fleet-hub:/var/lib/brigade/fleet-hub-pre-upgrade.db "$backup_path"
chmod 0600 "$backup_path"
podman exec brigade-fleet-hub rm /var/lib/brigade/fleet-hub-pre-upgrade.db
systemctl --user stop brigade-fleet.service
After the backup succeeds and the user service stops, build and deploy the candidate with the steps above, record its new digest, and put it in the installed unit. Starting it may migrate the persistent database.
Roll back
Load the archive, check the restored image ID, render the old digest into the unit, and start the generated service again. Set the three variables from your saved archive name, digest and pre-upgrade backup:
set -euo pipefail
# Set these from the saved archive name, digest, and pre-upgrade database backup.
archive="$HOME/.local/share/brigade-fleet-hub/archives/brigade-fleet-hub-REPLACE_WITH_RECORDED_DIGEST.tar"
previous_digest="sha256:REPLACE_WITH_RECORDED_DIGEST"
backup_path="$HOME/.local/share/brigade-fleet-hub/backups/fleet-hub-pre-upgrade-REPLACE_WITH_TIMESTAMP.db"
previous_ref="localhost/brigade-fleet-hub@${previous_digest}"
image_id_file="${archive%.tar}.image-id"
previous_id="$(cat "$image_id_file")"
test -n "$previous_id"
podman image load --input "$archive"
restored_id="$(podman image inspect --format '{{.Id}}' "$previous_ref")"
test "$restored_id" = "$previous_id"
systemctl --user stop brigade-fleet.service
podman run --rm --user 0:0 \
--volume brigade-fleet-state:/var/lib/brigade \
--volume "$backup_path:/restore/fleet-hub.db:ro,Z" \
--entrypoint python "$previous_ref" -c 'import os,shutil,sqlite3,tempfile
database="/var/lib/brigade/fleet-hub.db"
source="/restore/fleet-hub.db"
if not os.path.isfile(source) or os.path.getsize(source) == 0: raise SystemExit("Backup must be a nonempty regular file")
fd, staged = tempfile.mkstemp(prefix=".fleet-hub-restore-", dir=os.path.dirname(database))
os.close(fd)
try:
shutil.copyfile(source, staged)
source_connection=sqlite3.connect(staged)
target_connection=None
try:
result=source_connection.execute("PRAGMA integrity_check").fetchone()[0]
if result != "ok": raise RuntimeError(result)
target_connection=sqlite3.connect(database)
source_connection.backup(target_connection)
finally:
if target_connection is not None: target_connection.close()
source_connection.close()
os.chown(database, 10001, 10001)
finally:
if os.path.exists(staged): os.remove(staged)'
sed "s|REPLACE_WITH_RECORDED_DIGEST|${previous_digest}|" \
ops/fleet-hub/quadlet/brigade-fleet.container \
> "$HOME/.config/containers/systemd/brigade-fleet.container"
chmod 0644 "$HOME/.config/containers/systemd/brigade-fleet.container"
systemctl --user daemon-reload
systemctl --user restart brigade-fleet.service
curl --fail --max-time 5 http://127.0.0.1:3774/health
Notes
- Rootless UID mapping must make volume UID 10001 writable. The volume unit declares the owner UID and group GID. Confirm that on your Podman version before you rely on it.
- Quadlet generates the service. Start or update it with
systemctl --user restart, which starts an inactive service and reloads an active one. Do not enable the generated unit directly. Its[Install]section supplies the generator’s startup wiring. - Podman Compose is not Podman’s own Compose implementation. It calls an external provider such as
docker-composeorpodman-compose. - On Docker Desktop and Podman Desktop, containers and named volumes live inside the desktop’s Linux VM. Back up and restore against that VM’s storage.
Security and operations boundary
The image binds to 0.0.0.0 inside the container. A bare docker run -p 3774:3774 publishes plain HTTP on every host interface. Use the explicit loopback publication in these recipes.
Both recipes publish only on the host’s loopback address and mount the token as a protected file. Plain HTTP is local-only under that rule, and Docker Compose needs Engine 28.0.0 or newer for it to hold against hosts on the same layer-2 network.
The recipes include no HTTPS front end for other machines, and clients refuse plain HTTP to a remote hub. The tested HTTPS layout is a TLS proxy that shares the hub’s network namespace. The hub binds to numeric loopback with --trust-forwarded-proto, and the proxy overwrites X-Forwarded-Proto, so the hub sees a loopback peer. A proxy on a separate container network is unsupported, because host loopback publication does not make its peer loopback. Do not weaken the hub’s check to make that topology work. Keep the hub on a private network and never publish it through a public tunnel.
Before an upgrade, stop writes and take a SQLite online backup to a separate local path (for example with Python’s sqlite3.Connection.backup). Test a clean restore with the candidate image. Upgrade one instance, then check health, node authentication, event ingestion, dashboard enrollment and restart retention. Keep the database backup and the image archive. Compose rolls back to the archived image ID, and Quadlet rolls back to its saved image digest. Restoring a schema-compatible backup can lose every write made after it. Never downgrade a live database in place.