DevRunbook-Public/docs/31-first-run-and-instance-lifecycle.md

31 — First run and instance lifecycle

Instance states

• uninitialized — database reachable, no completed setup record;
• initializing — one setup transaction/lease active;
• ready — owner, personal workspace and instance configuration created;
• maintenance — operator intentionally prevents ordinary traffic;
• migration_required — application version cannot serve until migration action;
• recovery_required — configuration or encryption-key dependency is missing.

Readiness returns false for every state except ready; liveness remains process-focused.

Bootstrap protection

When setup is incomplete:

• only health and setup endpoints are available;
• all other routes redirect or return a setup-required error;
• a configured BOOTSTRAP_TOKEN must be supplied to begin and complete setup;
• if no token is configured, setup is allowed only from loopback or an explicitly trusted local network policy;
• reverse-proxy headers are trusted only from configured proxy addresses.

The UI clearly warns when setup is exposed without a token.

Setup transaction

1. Acquire a database advisory lock or unique setup lease.
2. Re-check that setup is incomplete.
3. Validate instance name, public URL and owner credentials.
4. Create owner user.
5. Create personal workspace and owner membership.
6. Store non-secret instance configuration and digest.
7. Import and verify all 28 P0 built-in packages.
8. Mark setup complete in the same transaction for identity/config records.
9. Enqueue non-critical search projection and example verification jobs.
10. Revoke the bootstrap token or mark it no longer accepted.

Catalog import failure blocks completion. Optional Gitea setup does not.

First-run experience

Screens:

1. System checks
2. Instance identity
3. Owner account
4. Storage and retention
5. Optional Gitea connection
6. Built-in catalog verification
7. Guided sample composition
8. Completion and backup warning

The sample composition uses a bundled example Repository Profile and creates an explicit sample generated task. It never creates fake live repository or production data.

Setup concurrency

A second browser attempting setup receives a safe “setup already in progress” state. If the lease expires because the process crashed, setup may restart after verifying no owner/setup completion exists. Partial users without a completed setup transaction must not remain active.

Recovery states

Missing encryption key

The application may start but readiness is false when encrypted integration secrets exist and required key versions are unavailable. The UI explains which key versions are missing without revealing key material.

Migration required

The web process displays an operator page with current and required schema versions. It does not automatically perform destructive migration unless explicit configuration permits the documented migration mode.

Artifact storage unavailable

The instance remains ready only when prompt generation can operate safely; binary exports are degraded and visibly disabled. Operators receive a health finding.

Ownership transfer

Ownership transfer requires:

• current owner recent authentication;
• target active user;
• explicit confirmation;
• transaction that changes both instance roles;
• revocation of privileged sessions as configured;
• audit event.

There must always be exactly one active instance_owner after setup.

User and instance deletion

The MVP does not provide a one-click “delete instance” UI. Operator documentation provides backup-aware container/database removal steps.

User deletion:

• disables login immediately;
• offers export before destructive removal;
• explains treatment of authored playbooks, audit records and frozen generated tasks;
• schedules retention-safe cleanup;
• never silently removes shared workspace evidence.

Upgrade lifecycle

• startup identifies application and schema versions;
• preflight checks database, artifact storage, content packages and encryption keys;
• incompatible versions enter migration_required rather than crash-looping without explanation;
• after upgrade, a smoke job checks catalog, composition and artifact digest behavior;
• prior application image is retained until operator acceptance.