# Deployment and recovery ## Process model Run one service process per database on a local persistent filesystem. Place HTTPS termination in front of the service for remote access. Configure ingress request-size limits, connection timeouts, and rate limiting. Do not expose the service directly through an unprotected public listener. Forwarded headers are not trusted by the application. The process needs read/write access only to its data directory. Outbound DNS and public HTTPS are required for event delivery. Ingress access logs must omit credentials and request bodies. When capability URLs are enabled, redact entire MCP endpoint paths in proxies, monitoring, traces, and error reporting. ## Containers Build from the repository root: ```sh docker compose build docker compose run --rm dot2api init ``` Use `docker compose run --rm dot2api` followed by the administrative subcommand and its required options to provision identities and credentials. Then start the service: ```sh docker compose up -d docker compose ps ``` The image runs as UID/GID 10001 and persists `/data` in a named volume. The Compose definition binds port 8788 only on host loopback. The container health check calls `/readyz`. Configure the host HTTPS proxy separately. The filesystem is read-only outside the data volume and temporary filesystem; Linux capabilities are dropped. Do not run administrative `init` against a database whose encryption key has been lost. Restore the original key first. A replacement key cannot decrypt existing callback secrets. ## Operations Inspect `dot2api status` for task and delivery counts and `dot2api audit` for recent task/subscription metadata. Monitor readiness, disk usage, dead deliveries, queue age, and lease failures. Audit records do not contain instructions, results, bearer credentials, or signing secrets; they are not a complete HTTP access ledger. Background-cycle failures are logged without input values. There is no built-in metrics exporter or automatic data-retention job. Provision external monitoring and a storage retention procedure suitable for the installation. Do not alter live tables without a verified backup and a maintenance window. Shutdown stops reserving new deliveries and waits for the active callback operation. Delivery reservations recover after expiration if shutdown is interrupted. The application does not guarantee cancellation of an already transmitted callback. ## Backup and restore Use `dot2api backup --output` with a new destination path. The command uses the SQLite backup API and may run while the service is active. Store the encryption key separately in protected backup storage. Both database and original key are required to restore subscriptions. For restoration, stop the service, retain the existing data directory as a rollback copy, create a clean protected data directory, and place the database at `dot2api.sqlite3` and the original key at `encryption.key`. Set directory permissions to 0700 and file permissions to 0600 with the service account as owner. Do not combine a restored database with old WAL or SHM files. Start the service, check readiness and status, then renew expired subscriptions and credentials as required. Restored state may replay previously delivered events; consumers must deduplicate. ## Upgrades Back up data and key, stop the process, install the selected release with its lockfile, and restart. Schema versions are checked at startup; unsupported databases are rejected rather than silently rewritten. This release has schema version 1 and no migration from unrelated database layouts. Rollback requires the corresponding pre-upgrade database and key, not only older source code.