160 lines
5.5 KiB
Markdown
160 lines
5.5 KiB
Markdown
# 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.
|