Operating a Compose installation

All commands use the wrapper deploy/compose/quavon. It runs admin commands in the application image (docker compose run --rm --no-deps api …) for the Compose project quavon and returns their exit code. The stack must be running.

Command	Purpose
quavon install [options]	Install or update (see install.md)
quavon status	State and health of all services
quavon logs [service] [-f]	Last 200 log lines, optionally followed
quavon doctor [--json]	Check configuration and dependencies (see doctor.md)
quavon doctor --sandbox-smoke	Run the sandbox escape smoke test on every runner (see sandbox.md)
quavon setup-token	One-time setup link for registering a GitHub App
quavon break-glass	One-time instance admin link
quavon keys status / quavon keys rotate	Encryption key status and rotation

There are no backup, restore or upgrade commands; see backup.md and upgrade.md. Problems are listed by symptom and doctor code in troubleshooting.md.

doctor and keys additionally receive the migrator database URL (mounted read-only from secrets/database_migrator_url), which the api service itself does not need.

Break-glass access

Use break-glass when nobody can sign in as instance admin, for example after the GitHub App was deleted or its credentials broke.

./deploy/compose/quavon break-glass

The command prints a link that is valid for 15 minutes and can be used once. The resulting session has no user, is limited to instance administration (GitHub Apps, settings, audit) and expires after one hour. Issuing a link is recorded in the instance audit log. Treat the link like a password: do not paste it into tickets or chats.

Encryption key rotation

The procedure follows ADR-0008. The Compose file passes QUAVON_ENCRYPTION_KEY from secrets/encryption_key; previous keys are given through QUAVON_PREVIOUS_ENCRYPTION_KEYS (comma-separated, or QUAVON_PREVIOUS_ENCRYPTION_KEYS_FILE).

1. Back up deploy/compose/secrets/.
2. Generate a new key: openssl rand -base64 32.
3. Make the old key a previous key: store the current content of secrets/encryption_key in a new secret file and pass it as QUAVON_PREVIOUS_ENCRYPTION_KEYS_FILE to api and worker (Compose override file).
4. Write the new key to secrets/encryption_key (no trailing newline is required; one is ignored).
5. Restart: docker compose -p quavon up -d from deploy/compose.
6. Re-wrap stored values: ./deploy/compose/quavon keys rotate (add --dry-run first if you like). Exit code 2 means a value could not be decrypted; the output names the table and row.
7. Check: ./deploy/compose/quavon keys status must report that all values are on the current key (exit 0). quavon doctor reports leftovers as QD402.
8. Remove the previous key from the configuration, restart, and destroy the old key material once backups that need it have expired.

Logs

./deploy/compose/quavon logs            # all services
./deploy/compose/quavon logs api -f     # follow the API
./deploy/compose/quavon logs init       # role creation and migrations

Logs never contain secrets or tokens. Log verbosity is set with LOG_LEVEL in .env (re-run quavon install or restart after changing it).