115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# 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.
|