# 16 — Deployment and Unraid operations

## Reference deployment

The MVP ships as Docker images and a Docker Compose definition suitable for ordinary Linux hosts and Unraid templates.

Services:

- `devrunbook-web`
- `devrunbook-worker`
- `postgres`

Optional reverse proxy and external PostgreSQL are supported but not required.

## Volumes

Recommended logical mounts:

```text
/config       application configuration and non-secret instance metadata
/content      optional operator-supplied playbook packages, read-only or controlled import
/artifacts    generated Markdown and Run Pack files
/backups      operator backup output
postgres-data database volume
```

Encryption master keys are environment/secret inputs and are not stored in ordinary backup volume by default.

## Ports

Expose one application HTTP port. PostgreSQL should remain internal unless the operator explicitly requires external administration.

## Environment categories

- `DATABASE_URL`
- `PUBLIC_BASE_URL`
- `SESSION_SECRET`
- `INTEGRATION_ENCRYPTION_KEY`
- `INTEGRATION_ENCRYPTION_KEY_VERSION`
- `CONTENT_ROOT`
- `ARTIFACT_ROOT`
- `MAX_IMPORT_BYTES`
- `MAX_ARTIFACT_BYTES`
- `GITEA_PRIVATE_NETWORK_POLICY`
- `LOG_LEVEL`
- retention values
- first-run/bootstrap configuration

The actual implementation must publish a complete `.env.example` with safe descriptions and no real values.

## First-run wizard

1. verify database and migration state;
2. create first administrator account;
3. configure instance name and public URL;
4. confirm artifact and retention settings;
5. optionally configure Gitea;
6. import/verify built-in catalog;
7. complete a sample composition without fake production data.

First-run state is explicit and cannot be reopened without authentication after completion.

## Unraid template requirements

- clear container icon and WebUI URL;
- required paths and their purposes;
- generated secrets guidance;
- default bridge network with reverse-proxy instructions;
- PostgreSQL dependency documented;
- healthcheck visible;
- update procedure;
- backup paths;
- no privileged mode;
- non-root container user where possible;
- read-only root filesystem considered and documented.

## Backup

A supported backup includes:

- PostgreSQL logical dump with version metadata;
- artifact directory or selected artifact retention subset;
- operator playbook content directory;
- instance configuration excluding plaintext secrets;
- manifest with application version and checksums.

The encryption key must be backed up separately and securely. Without it, encrypted integration tokens cannot be recovered; this must be stated prominently.

## Restore

1. deploy compatible application version;
2. restore PostgreSQL into an empty database;
3. restore artifact/content directories;
4. provide the correct encryption key versions;
5. run migration status check;
6. start worker then web or documented order;
7. verify health, catalog, profiles, historical runs and one artifact digest;
8. test an integration connection without exposing token.

## Upgrade

- read release notes;
- create database and artifact backup;
- pull images;
- run migration preflight;
- apply migrations according to policy;
- start services;
- verify health and core smoke flow;
- retain previous image until acceptance;
- document rollback limits for schema changes.

## Operational smoke checks

- login;
- library search;
- open built-in playbook;
- preview with manual profile;
- generate run;
- download Markdown;
- worker completes test job;
- Gitea health when configured;
- restart persists state.

## Reverse proxy and trusted LAN boundary

Production internet-facing deployments must terminate HTTPS at a maintained
same-host reverse proxy and set `PUBLIC_BASE_URL` to the external `https://`
origin. Keep the reference web port bound to loopback. `TRUSTED_PROXY_CIDRS` is
reserved configuration and is not currently an enforcing control, so never
expose the direct HTTP port or rely on forwarded headers from the general LAN or
internet. Verify that sign-in returns an `HttpOnly`,
`SameSite=Lax`, `Secure` session cookie and that HSTS, CSP, frame, MIME and
referrer headers are present. Direct HTTP is supported only on a deliberately
trusted, access-controlled LAN; browsers correctly omit the `Secure` cookie
flag in that explicitly weaker mode.

## Runtime limits and writable paths

The Compose baseline drops every Linux capability, forbids privilege gain,
uses a read-only application root filesystem, limits application services to
256 PIDs/1 GiB and the one-shot migrator to 128 PIDs/512 MiB. Only `/tmp` is a
temporary writable filesystem. `/artifacts` is writable for generated output;
`/operator-content` is mounted read-only. PostgreSQL alone writes its dedicated
data volume. Increase limits only from observed load and record the reason.

The all-in-one image necessarily retains a small root supervisor boundary to
start its private PostgreSQL and application processes. Prefer the separated
Compose services when stronger process isolation is required. Its `/config`
mount and declared temporary paths are the only intended persistence/writable
boundaries.

## Storage and backup evidence

Operations reports database and artifact sizes plus artifact-filesystem
headroom. Less than 15% free artifact storage requires prompt operator action:
verify a restorable backup, apply governed retention and expand the volume
before PostgreSQL or artifact writes fail. The dashboard says “observed” only
when DevRunbook has explicit backup evidence; it never treats file age, an
external scheduler or an empty error log as proof of backup success.