03 / 13
Installation
GHCR image, release binaries, source build and deployment topology; compose is development-only
Runtime shape
One Go binary with the console embedded, plus two external runtime dependencies (age ships as a Go library):
| Dependency | Purpose | Version |
|---|---|---|
| PostgreSQL client tools | pg_dump / pg_restore | 14–18 (in image; install locally for binaries) |
| age (library) | encryption/decryption | Go library filippo.io/age built in — no age CLI needed |
| S3-compatible storage | remote commit (optional, recommended) | S3 / R2 / B2 / MinIO |
Prebuilt artifacts (recommended)
Two official channels, both published per v* tag after the full CI gate:
GHCR container image (linux/amd64 + linux/arm64, tags <version> and latest):
docker run -d -p 8080:8080 -v supacove-data:/app/data \
ghcr.io/web-casa/supacove:latestThe image ships the PostgreSQL client matrix 14–18 (no host pg_dump needed) and runs as non-root (UID 10001). For a production compose example and the environment variable table see the repository's docs/deployment.md.
Release binaries (linux/darwin × amd64/arm64, tar.gz + SHA256SUMS): the
web console and the SQLite control plane are embedded — no Docker needed.
The only external dependency is a host pg_dump (brew install postgresql@17 plus the keg-only bin directory in PATH on macOS;
postgresql-client-17 on Debian/Ubuntu; client major must be ≥ the source
major). systemd example and upgrade steps: the standalone-binary section of
docs/deployment.md.
Build the image locally (optional)
docker build --target runtime -t supacove:<tag> .The release runtime stage is the Dockerfile's default (last) stage; the
ADR-004 experiment image (embedded PostgreSQL server) lives in a separate
Dockerfile.spike and never ships.
Source
# Needs Node 22 (console frontend) and Go 1.26.9+ (matches go.mod)
make build # = frontend + backend: builds the console, embeds it, emits bin/supacovemake backend alone only compiles Go: without the frontend embedded via
make frontend, the instance answers page requests with 503. Source
deployments must use make build.
Directories and permissions
SB_DATA_DIR(default./data,/app/datain the image): master secret, metadata database, staging, expected 0700. UID 10001 applies to the container image only; source/systemd deployments run as whatever user you choose — give that user exclusive ownership of the data directory.- The master secret file is 0600 and symlink-refusing; the age identity does NOT belong in the data directory.
docker compose: development only
The bundled compose.yaml sets SB_INSECURE_COOKIE=1 and fixed development
passwords and starts dev PostgreSQL/MinIO — local experimentation only. For
production, ensure:
- TLS in front (session cookies are
Secure; plain-HTTP logins failing is a deliberate fail-closed default unlessSB_INSECURE_COOKIE=1, local only). - The data volume is backed up independently — it holds the master secret.
Upgrading
The install commands on this page are fresh-install examples (hence the
supacove-datavolume). Upgrading from a pre-renamesupabackupdeployment is NOT just rerunning them: stop ALL legacy processes (server and CLI) and keep the originalsupabackup-datavolume / systemd directories — the data files migrate automatically on first start. See the rename upgrade notes in the repository's docs/deployment.md.
Stop → replace binary/image → start. Schema migrations run at startup with
per-version pre-migrate snapshots. A shutdown that lands on a running backup records interrupted (not failed);
ciphertext meeting the resume conditions (interrupted + locally committed +
recorded remote intent + artifact and manifest readable + usable
destination) is re-uploaded at the next startup.
Last updated