This commit is contained in:
DevRunbook release export
@@ -0,0 +1,159 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user