DevRunbook final handoff

Delivered product

DevRunbook 0.1.0-rc.1 is a self-hosted, no-arbitrary-execution control plane that turns governed playbooks, repository profiles, intent, constraints and an autonomy level into deterministic prompts and Run Pack archives. The release contains all 28 P0 packages, a searchable library, guided composer, immutable run history, package authoring, read-only Gitea intelligence, local identity, operations/audit views and production Docker/Unraid tooling.

Release identity

Version: 0.1.0-rc.1
Evidence commit: post-audit qualification on 2026-07-30 (see release-evidence.json)
Database schema: nine forward migrations, 0000 through 0008
Runtime: Node.js 24, PostgreSQL 17.9, linux/amd64
Validation deployment: private validation host (address intentionally redacted)
Web image ID: sha256:9679fab3cc033705f27a8f12eb92430f73f8b9f770cc309c8466f5a00e2e494f
Worker image ID: sha256:982409b776484de5c14e1bbd206bf12f9379570b7f21562629d86ff42e38b63a

Verified capabilities

28/28 built-in packages import idempotently and the separate 72-entry roadmap catalog validates.
Library search, facets, sorting, URL state, favorites, collections and lifecycle/quality presentation are implemented.
Manual and Gitea-derived repository profiles retain immutable revisions, protected paths, inert commands and historical run snapshots.
Observe through Repair autonomy, live deterministic preview, provenance, compatibility checks and blocking prompt lint are implemented.
All 28 supplied minimal examples render byte-identically through the production TypeScript composer.
Plain prompt, Markdown, AGENTS recommendation and deterministic Run Pack ZIP exports are persisted, authorized and re-importable without extraction.
Local first-run ownership, password authentication, hashed/revocable sessions, invitations, password reset and workspace authorization are enforced.
Gitea is read-only and optional; retained local snapshots/profiles remain usable during outage or after integration removal.

Validation evidence

Gate	Result	Evidence
Clean installation	Pass	Isolated Compose project built from the documented path; setup `201`, repeat setup `409`, exact 28 built-ins, healthy after restart.
Migrations	Pass	Empty PostgreSQL 17.9 database applied all nine migrations; 36/36 integration tests passed and readiness remained `ready` after restart.
Built-in catalog	Pass	`scripts/validate_pack.py`: 28 P0, 6 normative examples, 72 roadmap entries, 9 schemas and valid API/spec contracts.
Core browser flows	Pass	Live library/composer/export/Gitea/Prompt Lab history plus M8 collection, operations and invitation flows; desktop and 390×844 checks; final fresh tab had no console warnings/errors.
Backup/restore	Pass	Strict-checksum backup `pre-m8-b2fb5a5`; isolated restore matched users, runs, artifacts, audits, migration count and all artifact SHA-256 values.
Security checks	Pass	11/11 application security tests; dependency audit has no high/critical; Trivy web/worker 0 high/critical; Gitleaks 153 commits/0 leaks; licenses classified.
Performance targets	Pass	10,000 versions, 30 iterations: search P95 241.913 ms (<500); detail P95 24.469 ms (<400).
Accessibility	Pass	Axe scanned Start, composer, Projects, My tasks, account and Management plus English/Dutch simple/expert matrices in desktop and narrow projects: 24/24 tests passed with no serious/critical findings.
Operations hardening	Pass	Unraid inspection proved read-only roots, all capabilities dropped, PID 256, 1 GiB memory and 64 MiB tmpfs for web/worker; status distinguishes observed evidence from unknown state.
Restart and restore	Pass	Restart retained 1 owner and 28 built-ins; isolated PostgreSQL restore matched 1 owner, 28 playbooks and 9 migrations before cleanup.

The machine-readable requirement/gate matrix is release-evidence.json. Supporting reports are under evidence/ and milestone-by-milestone commands are recorded in CURRENT_STATE.md.

Deployment

From a release checkout, copy .env.example to a mode-0600 environment file and set independent random POSTGRES_PASSWORD, SESSION_SECRET, INTEGRATION_ENCRYPTION_KEY, BOOTSTRAP_TOKEN, PUBLIC_BASE_URL and DEVRUNBOOK_PORT values. Then run:

docker compose -p devrunbook-prod --env-file .env build
docker compose -p devrunbook-prod --env-file .env up -d
docker compose -p devrunbook-prod --env-file .env ps
curl --fail http://127.0.0.1:3000/health/live
curl --fail http://127.0.0.1:3000/health/ready

Complete /setup with the bootstrap token. Keep registration closed unless an operator deliberately changes policy. Gitea configuration is optional.

For Unraid, set UNRAID_APPDATA_ROOT, create the restricted PostgreSQL, artifact, content and backup paths described in docs/operator-guide.md, and use:

export COMPOSE_FILE=docker-compose.yml:unraid/docker-compose.unraid.yml
docker compose -p devrunbook-prod --env-file .env build
docker compose -p devrunbook-prod --env-file .env up -d

Upgrade

Create and copy a verified backup first. Run the read-only preflight:

docker compose -p devrunbook-prod --env-file .env run --rm migrate \
  ./packages/db/node_modules/.bin/tsx scripts/release/migration-preflight.mts

If the outcome is ready, stop web/worker, build the candidate, run the one-shot migrate service and start web/worker. Down migrations are not provided; rollback means restoring the pre-upgrade backup into an empty database and starting the compatible retained image.

Backup and restore

sh scripts/release/backup.sh \
  --project devrunbook-prod \
  --env-file "$(pwd)/.env" \
  --output /absolute/new/backup/directory \
  --application-version 0.1.0-rc.1 \
  --application-commit "$(git rev-parse HEAD)"
sha256sum --check --strict /absolute/new/backup/directory/SHA256SUMS

Preserve every integration encryption key version separately in an operator secret store. Restore only into a new devrunbook-*-restore-* project:

sh scripts/release/restore-empty-target.sh \
  --project devrunbook-release-restore-001 \
  --backup /absolute/backup/directory \
  --env-file /absolute/restricted/restore.env

Verify readiness, authorization, counts and artifact/run digests before removing the exact temporary restore resources.

Known limitations

Release qualification covers linux/amd64; no other architecture is claimed.
Gitea is the only forge adapter and remains strictly read-only.
There is no arbitrary repository command execution, Codex CLI bridge, semantic/vector search or automatic evaluation runner in this MVP.
Product telemetry is disabled. Operators use health endpoints, structured logs, the operations console and audit events; no Prometheus endpoint ships.
Docker/external logging owns operational-log rotation. Audit-event pruning is manual to preserve append-only governance until a reviewed archival policy is adopted.
Development-only dependency findings, if any, remain outside the production runtime; the final production audit is enforced at high severity.

Operator actions

Replace validation-only secrets and hostnames; never copy the validation env.
Store encryption keys and database credentials outside ordinary backups.
Configure reverse proxy TLS, Docker log rotation and off-host backup copies.
Monitor Docker storage capacity and retain write headroom for PostgreSQL; pruning unused build cache is safer than allowing the database volume to fill.
Run artifact retention on the desired operator schedule.
Review release evidence and limitations before creating a release tag; no tag was created automatically.

7.6 KiB Raw Permalink Blame History Unescape Escape