Operations
For PR scope, review waves, the CI/visual-QA boundary, and the exact-head merge gate, see Deliver changes quickly and safely.
For an existing deployment, use the upgrade and data retention runbook before changing images, Compose files, or named volumes.
Configuration
Copy .env.example to .env. The most important settings are:
| Variable | Purpose |
|---|---|
APP_NAME | Shared display name for the portal, Forgejo navbar, and browser titles; defaults to OpenFace |
OPENFACE_ADMIN_USER | Initial Forgejo administrator |
OPENFACE_ADMIN_PASSWORD | Bootstrap password; change it before shared use |
PUBLIC_BASE_URL | Canonical gateway URL used by Forgejo and embedded links |
OPENFACE_HTTPS_PORT | Host HTTPS port |
POSTGRES_USER / POSTGRES_PASSWORD | Credentials shared by the three internal PostgreSQL databases |
DISABLE_REGISTRATION | Keeps public self-registration closed when true |
MAX_RUNNING_SPACES | Maximum simultaneous Space containers |
IDLE_TIMEOUT_MINUTES | Optional inactivity shutdown; 0 disables it |
Backups
Create PostgreSQL dumps for forgejo, openface_metrics, and openface_maintenance. The openface_metrics dump includes the v0.6.0 metric_events ledger used for measured views, completed downloads, time-series activity, and active likes. Runner startup creates the ledger and idempotently backfills legacy counters; it does not prune events, so keep the dump with its restore evidence. For a v0.4.0 installation that has not completed the v0.5.0 migration, the openface_metrics dump does not include the legacy pipeline audit/history or reconciliation state: that state remains in /data/agents/pipelines/pipeline-audit.db inside the openface_agent-metrics-data volume. After the migration, the authoritative pipeline state is in the openface_pipeline schema of the openface_metrics database and is covered by that dump. Also back up the named volumes openface_forgejo-data, openface_agent-metrics-data, openface_maintenance-agent-data, openface_shared-token, and openface_forgejo-runner-data, plus openface_mcp-state when the MCP profile is enabled. The MCP named volume contains write-safety state such as its HMAC key. Archive the operator-selected OPENFACE_MCP_STATE_DIR bind mount separately with its registry and lifecycle-audit state, plus the protected source files referenced by OPENFACE_MCP_FORGEJO_USER_TOKEN_FILE and OPENFACE_MCP_ADMIN_INTERNAL_TOKEN_FILE. Never put their contents in the manifest. Test restore procedures before relying on the backup; the complete sequence is in the upgrade runbook.
For a Proxmox deployment, follow Proxmox LXC deployment.
TLS
The gateway creates a self-signed development certificate when none exists. For a shared deployment, place a trusted certificate at gateway/certs/cert.pem and its private key at gateway/certs/key.pem, then set the public URL and port in .env before restarting.
Security boundary
OpenFace is intended for trusted local or private-network collaboration. It is not a hardened multi-tenant sandbox. The Space runner has host Docker control, so only trusted maintainers should be able to create or change runnable Space repositories.
Keep Forgejo registration disabled, rotate the bootstrap password, review Dockerfiles, protect backups, and do not expose token-bearing logs or clone URLs.
Useful commands
docker compose ps
docker compose logs --tail=200 gateway frontend forgejo spaces-runner
docker compose up -d --build
docker compose down