DevRunbook-Public/docs/16-deployment-unraid.md

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:

/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.