Start, stop and template composition
deploy/run.sh [--stage] up runs in the foreground; up -d detaches. At start, envsubst renders the core and enabled additive feature templates, then Compose config merges and validates a mode-0600 generated file. $$ is a literal dollar. Disabled features are removed with up --remove-orphans. The one-shot keycloak-init is removed only after it exits and dependants have started.
Inspection and control commands such as down, stop, restart, ps and logs use the project label without reading secrets or rendering files. Restart keeps existing images/configuration. Owner-controlled service start applies changes. A lasting systemd stop uses systemctl stop. Down keeps data; reset deletes local data and generated secrets in dev only.
Secrets, ownership and local data
Data is bind-mounted under deploy/data/<environment>. Secrets files are gitignored: secrets.dev.sh, secrets.stage.sh and secrets.sh for prod. Individual secret files are rendered into mode-0700 in-memory runtime directories and mounted read-only, not passed as environment variables. Values are not printed. Missing values fail by name. Initial account credentials are consumed only by create-admin-user.sh.
Stage/prod units run as separate users/groups from /home/avarc-<environment>. RuntimeDirectory is removed at stop. Host settings resolve environment → secrets file → defaults. IMAGE_NAMESPACE selects project images; UPSTREAM_REGISTRY independently selects upstream registry/cache images.
Database inspection and imports
DB_TAILNET=true enables the db-tailnet and dbtool templates together in dev/stage, never prod. Tailnet ACLs govern reachability. avarc_ro is read-only in public and avarc; Keycloak and legacy personal-data access are separately opt-in via create-db-user.sh flags or settings. CloudBeaver has its own login, no anonymous access, regenerated read-only connection configuration and no custom user connections. Admin credential changes reset its internal account store. SQLite is not supported by the referenced web build.
import-sql.sh is dev/stage-only. A plain SQL file loads transactionally into a separate schema (default legacy, not public/avarc), unless the file names a schema. Mapping legacy data is separate. No import is performed here.
Backups and a careful restore
backup-db.sh creates complete-before-rename mode-0600 pg_dump -Fc files for avarc and Keycloak, globals SQL and, when available, realm user export. Retention defaults to seven days. Stage/prod backup timers run nightly at 03:00 with Persistent=true; installation does not enable them. The database must already be running. Off-host copies are outside the repository.
restore-db.sh can select a stamp and databases. In-place restore requires backend, Keycloak and dbtool stopped, takes a fresh backup unless explicitly bypassed, and confirms the environment. Globals are optional. Scratch restore uses a throwaway same-image container with no published port or volume, restores roles, compares migration history and record counts, then removes it without touching the environment.
Images, stage rollout and production releases
Project images are ingress, backend, frontend and Keycloak. Registry namespaces containing a slash trigger pulls before start: four attempts, fifteen-second retry delay by default. Pull failure stops startup. Stage follows snapshot; a restart of the unit pulls it. Roll back using sha-<commit> overrides. Prod accepts exact release tags from a clean checkout. Project images have dd.watch=false; upstream images remain watched.
Stage verification expectations: /health → 200; /api/hello → 401 anonymously; OpenID configuration → 200; origin → 307. These are expected values, not live results from this page.
Network, admin access and observability
Docktail terminates TLS for the localhost-published ingress. Keycloak admin has a separate tailnet address and localhost ports 8180/8181/8182; ingress does not expose it. Backend and frontend have no published host ports. Application and Keycloak databases share PostGIS, trading simplicity for a common failure/upgrade domain.
Docker JSON logs rotate at 10 MB × 5. All services have health checks. Tiny Health Checker covers backend readiness on 9091, frontend /health and ingress metrics; database and Keycloak use readiness. A private external metrics network publishes nothing. Slow SQL threshold is 500 ms. API docs, actuator and admin footer links are dev/stage-only.