Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,114 @@
+# 32 — Configuration reference
+
+## Configuration layers
+
+1. environment/secrets supplied by the operator;
+2. validated non-secret instance configuration stored in PostgreSQL;
+3. user preferences;
+4. request-specific choices.
+
+Server-only environment values never enter client bundles or generated prompts.
+
+## Required environment values
+
+| Variable | Requirement |
+|---|---|
+| `DATABASE_URL` | PostgreSQL connection string; never logged in full |
+| `PUBLIC_BASE_URL` | Absolute externally used URL |
+| `SESSION_SECRET` | Random value of at least 32 bytes |
+| `INTEGRATION_ENCRYPTION_KEY` | Base64-encoded 32-byte active key |
+| `INTEGRATION_ENCRYPTION_KEY_VERSION` | Stable operator-managed version label |
+| `CONTENT_ROOT` | Absolute container path to built-in/operator content |
+| `ARTIFACT_ROOT` | Absolute container path to generated artifacts |
+
+Optional old integration keys use a versioned secret-map format defined by the implementation and documented in `.env.example`.
+
+## Bootstrap and proxy values
+
+- `BOOTSTRAP_TOKEN` — recommended random single-use setup token.
+- `TRUSTED_PROXY_CIDRS` — reserved for a future trusted-proxy implementation;
+  it is validated but does not currently authorize forwarded headers. Do not
+  rely on it as a security control.
+- `MAINTENANCE_MODE` — explicit boolean.
+
+## Default limits
+
+| Setting | Default |
+|---|---:|
+| Compressed import | 10 MiB |
+| Expanded archive | 50 MiB |
+| Files per archive | 500 |
+| Single imported file | 5 MiB |
+| Rendered prompt | 2 MiB |
+| Raw repository evidence per composition | 256 KiB |
+| Single evidence snippet | 32 KiB |
+| Standard Run Pack | 5 MiB |
+| API request body excluding import | 2 MiB |
+| Gitea file response | 1 MiB per file |
+| Gitea files per snapshot | 200 |
+| Gitea redirects | 3 |
+| External request timeout | 15 seconds |
+| Composition timeout | 5 seconds |
+| ZIP generation timeout | 30 seconds |
+
+All limits are configurable within hard safety maxima validated by `schemas/instance-config.schema.json`.
+
+## Retention defaults
+
+- binary artifacts: 90 days;
+- immutable generated task text: indefinite for personal self-hosting;
+- repository snapshots: latest 20 plus any referenced by a profile/run;
+- audit events: 180 days;
+- operational logs: 30 days;
+- failed import staging: immediate deletion after safe error extraction;
+- expired invitations/reset tokens: 7-day cleanup grace.
+
+Retention jobs never delete records referenced by immutable audit or generated-task contracts without the explicit documented detachment behavior.
+
+## Gitea network policy
+
+Default is deny for loopback, link-local, metadata and private networks. Self-hosted private Gitea requires:
+
+- `GITEA_PRIVATE_NETWORK_POLICY=allow-explicit-hosts`; and
+- exact hostnames in the operator allowlist. CIDR entries are not currently
+  implemented.
+
+The application resolves all addresses before connection and after every redirect. Authentication headers never cross host boundaries.
+
+## Registration and telemetry
+
+- `REGISTRATION_MODE=closed` by default.
+- Product telemetry is disabled and unsupported in the reference MVP.
+- No external error-reporting SaaS is enabled by default.
+
+## Jobs
+
+Reference defaults:
+
+- worker polling interval: 2 seconds when notifications are unavailable;
+- lease duration: 60 seconds with heartbeat;
+- default max attempts: 3;
+- exponential backoff: 5 seconds to 15 minutes with jitter;
+- stale job warning: no progress for 5 minutes;
+- artifact cleanup and integration health checks: daily.
+
+## Logging
+
+- default level: `info`;
+- JSON in production, readable console format in development;
+- request IDs accepted only from trusted proxies or regenerated;
+- body logging disabled;
+- prompt and repository content excluded by default;
+- redaction paths include authorization, cookies, tokens, passwords, keys and encrypted envelopes.
+
+## Content and artifacts
+
+- Built-in content root is read-only in production.
+- Operator content may be a separate read-only mount imported through an admin action.
+- Artifact root must not be web-server static content.
+- Download routes set safe content types and `Content-Disposition`.
+- Filenames are sanitized metadata; storage keys are opaque random IDs.
+
+## Environment example
+
+`config/env.example` is a non-secret template. Codex must copy its fields into the implemented root `.env.example` and keep it synchronized with typed configuration tests.