Configuration readiness

The production profile validates deployment settings during startup. The server-role endpoint GET /api/admin/configuration-readiness returns those facts plus checks that need runtime state. It requires the app_admin authority and is available only when boot-fatal checks pass. Diagnostics never contain configured values.

Each fact has a stable id, the affected configuration subject, applicable runtime roles, a requirement, a status, an explanation, and a documentation link. Requirements are REQUIRED, RECOMMENDED, or OPTIONAL. Status is one of:

Status	Meaning
SATISFIED	The applicable check passed.
ACTION_REQUIRED	An applicable check failed. During startup, required deployment facts with this status prevent startup.
NOT_CONFIGURED	An optional setting is absent.
NOT_APPLICABLE	The check does not apply to this process's runtime roles.

The table names variables inside the application container. In the supported self-host stack, Compose maps POSTGRES_PASSWORD to DATABASE_PASSWORD and owns the runtime-role values.

Setting	Application environment variable
spring.datasource.url	DATABASE_URL
spring.datasource.username	DATABASE_USERNAME
spring.datasource.password	DATABASE_PASSWORD
hephaestus.runtime.server.enabled	HEPHAESTUS_RUNTIME_SERVER_ENABLED
hephaestus.runtime.worker.enabled	HEPHAESTUS_RUNTIME_WORKER_ENABLED
hephaestus.runtime.webhook.enabled	HEPHAESTUS_RUNTIME_WEBHOOK_ENABLED
hephaestus.host-url	APPLICATION_HOST_URL
hephaestus.security.encryption-key	HEPHAESTUS_SECURITY_ENCRYPTION_KEY
hephaestus.security.credential-encryption-key	HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY
hephaestus.webhook.secret	WEBHOOK_SECRET
hephaestus.sync.nats.enabled	NATS_ENABLED
hephaestus.sync.nats.server	NATS_SERVER
hephaestus.sync.nats.username	NATS_USERNAME
hephaestus.sync.nats.password	NATS_PASSWORD
hephaestus.auth.state-cookie-key	HEPHAESTUS_AUTH_STATE_COOKIE_KEY
hephaestus.llm.egress.allow-loopback	HEPHAESTUS_LLM_EGRESS_ALLOW_LOOPBACK
hephaestus.agent.image.require-digest	HEPHAESTUS_AGENT_IMAGE_REQUIRE_DIGEST
hephaestus.agent.image.reference	HEPHAESTUS_AGENT_IMAGE_REFERENCE
hephaestus.sandbox.container-runtime	SANDBOX_CONTAINER_RUNTIME
hephaestus.sentry.dsn	SENTRY_DSN

Runtime roles

Enable at least one of hephaestus.runtime.server.enabled, worker.enabled, or webhook.enabled; each accepts only true or false. The supported split topology enables only webhook on the webhook process, only worker on a remote worker, and server (optionally with a colocated worker) on the application process.

Database

Every role uses PostgreSQL. DATABASE_URL must be a PostgreSQL URL; the production profile adds the jdbc: prefix. Supply a non-empty username and password. This syntax check does not replace the connection and migration health checks performed by Spring Boot and Liquibase.

Remote databases require TLS. Prefer sslmode=verify-full, which encrypts the connection and verifies the server identity. sslmode=require encrypts without verifying identity. Production startup rejects plaintext remote connections unless HEPHAESTUS_DATABASE_ALLOW_INSECURE_REMOTE=true explicitly permits them.

Credential encryption

Set both encryption keys to exactly 32 printable, non-space ASCII characters and keep them with the database backup. The supported self-host setup generates them. Do not change the general encryption key on an existing installation. Rotate the credential key with the documented online procedure.

External URL

Set hephaestus.host-url to the public HTTPS origin, without credentials, a path other than /, a query, or a fragment.

Webhooks

Server and webhook roles require hephaestus.webhook.secret with at least 32 printable, non-space ASCII characters. The supported self-host setup generates an independent value; never reuse another application key.

NATS

Server and webhook roles require NATS and an explicit nats:// or tls:// URI with a host, an optional valid port, and no query, fragment, or non-root path. A worker-only process must disable NATS because its job queue is PostgreSQL-backed. The reference deployment requires NATS_USERNAME and NATS_PASSWORD. This check validates syntax and role consistency, not connectivity or JetStream health.

Login

The server role requires a Base64-encoded 32-byte hephaestus.auth.state-cookie-key and an enabled GitHub or GitLab sign-in provider in the database-backed provider catalogue. Environment provider entries are seeds, not the readiness authority. Slack and Outline are link-only providers and do not satisfy sign-in readiness. Worker and webhook roles do not load login providers.

LLM proxy

Worker roles must leave hephaestus.llm.egress.allow-loopback=false. Provider credentials and model configuration are database-backed runtime configuration and are not deployment settings.

Agent image

Worker roles require digest enforcement and a SHA-256-pinned hephaestus.agent.image.reference. See Release image lock.

Sandbox isolation

Set SANDBOX_CONTAINER_RUNTIME=runsc on workers after installing and configuring gVisor on the host. This recommendation is non-fatal.

Optional observability

Sentry is optional. When configured, hephaestus.sentry.dsn must use HTTPS. The fact is classified OPTIONAL and never prevents startup. Activating it requires the processing review in the processor checklist.

Frontend error rates include only browsers whose users accepted error monitoring. Treat them as consent-biased diagnostics, not as an availability metric or a basis for comparing deployments. Server-side error rates do not have this selection bias.