hephaestus-build · FelixTJDietrich · Aug 28, 2026 · Aug 28, 2026 · coderabbitai · Aug 28, 2026
diff --git a/.changeset/redacted-configuration-readiness.md b/.changeset/redacted-configuration-readiness.md
@@ -0,0 +1,10 @@
+---
+"hephaestus": minor
+---
+
+Production startup now reports all catalogued production configuration problems together without
+exposing configured values, and instance administrators can inspect redacted deployment and runtime
+readiness facts through the API. New self-hosted installations generate and preserve internal secrets
+with `setup.sh`. **Operators:** validate production settings against the configuration readiness guide
+before upgrading; the process now refuses to start when a catalogued required setting is missing or
+invalid.
diff --git a/AGENTS.md b/AGENTS.md
@@ -95,6 +95,11 @@ adding a rule there enables it nowhere. `webapp/AGENTS.md` § Linting has the re
 Holds wherever TypeScript is written here, the Bun agent trees and `scripts/**` included.
 `webapp/AGENTS.md` wins over it inside the SPA.
 
+Prefer typed Bun/TypeScript for repository automation, validation, and tests. Keep shell only at a
+real runtime boundary where Bun is unavailable, such as an end-user bootstrap that must run before
+the application toolchain is installed; keep that boundary POSIX-compatible and move its substantive
+test orchestration into TypeScript.
+
 - Separate import groups with blank lines wherever their relative evaluation order must not change; oxfmt sorts within each group.
 - **A leading `_` marks what the language or a tool reads that way** — an intentionally unused
   binding, a server field name (`_id`), a runtime global. It never marks something private, which

diff --git a/MIGRATION.md b/MIGRATION.md
@@ -82,6 +82,22 @@ review runs and no feedback is prepared about them.
 **Operator action after upgrading**: open **Practices → Review → When and where** and confirm the
 **People** and **Repositories** counts. Existing members need no action. If expected contributors are
 missing, follow [Who counts as a person](https://ls1intum.github.io/Hephaestus/admin/practice-review#who-counts-as-a-person).
+
+#### 🔴 Production configuration is validated before startup
+
+**Affected**: deployments that activate the `prod` Spring profile and have a missing, malformed, or
+role-inconsistent required setting.
+
+Production processes now validate the applicable requirements in the configuration readiness
+catalogue together and refuse to start until every reported error is resolved. The failure report
+identifies properties and documentation but never includes configured values.
+
+**Action**: before upgrading, compare every production role's settings with the
+[configuration readiness guide](https://ls1intum.github.io/Hephaestus/admin/configuration-readiness).
+Run a staging process with the production profile and correct every required setting it reports.
+After the server role starts, an instance administrator can inspect the redacted facts through
+`GET /api/admin/configuration-readiness`.
+
 #### 🔴 Practice area API names are replaced by practice group names
 
 **Affected**: anything calling the application API directly. The generated Hephaestus web client is

diff --git a/docker/self-host/.env.example b/docker/self-host/.env.example
@@ -2,7 +2,7 @@
 # Hephaestus self-hosted — environment
 # =============================================================================
 #
-#   cp .env.example .env    # then fill in every REQUIRED value below
+#   ./setup.sh              # generate internal secrets, then fill in external values
 #   docker compose up -d
 #
 # Full guide (read it first): https://ls1intum.github.io/Hephaestus/admin/install
@@ -29,23 +29,18 @@ ACME_EMAIL=
 # --- Secrets (REQUIRED — generate once, then never change) -------------------
 
 # Database password. Applied only when the data volume is first initialized.
-# Generate: openssl rand -hex 16
 POSTGRES_PASSWORD=
 
 # AES-256 key encrypting credentials at rest (and sealing the JWT signing key).
-# EXACTLY 32 bytes — i.e. 32 ASCII characters (a non-ASCII character costs more than one byte,
-# and the key is rejected at boot). Losing or changing it makes every stored provider
+# EXACTLY 32 printable, non-space ASCII characters. Losing or changing it makes every stored provider
 # token unreadable — treat it like the database itself and back it up.
-# Generate: openssl rand -base64 24 | cut -c1-32
 HEPHAESTUS_SECURITY_ENCRYPTION_KEY=
 
 # Base64-encoded 32-byte AES key sealing the short-lived OAuth state cookies.
-# Generate: openssl rand -base64 32
 HEPHAESTUS_AUTH_STATE_COOKIE_KEY=
 
 # Shared secret verifying inbound GitHub/GitLab webhooks (min 32 chars).
 # You will enter this same value on the GitHub side — see the install guide.
-# Generate: openssl rand -hex 32
 WEBHOOK_SECRET=
 
 # --- Login (at least one provider REQUIRED, or nobody can sign in) -----------

diff --git a/docker/self-host/compose.yaml b/docker/self-host/compose.yaml
@@ -2,7 +2,7 @@
 # Hephaestus — the one blessed self-hosted deployment
 # =============================================================================
 #
-#   cp .env.example .env   # fill in the values
+#   ./setup.sh             # generate internal secrets, then fill in external values
 #   docker compose up -d
 #
 # This file composes the same service definitions the maintainers deploy

diff --git a/docker/self-host/setup.sh b/docker/self-host/setup.sh
@@ -0,0 +1,79 @@
+#!/bin/sh
+
+set -eu
+umask 077
+
+directory=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+environment_file="$directory/.env"
+example_file="$directory/.env.example"
+
+command -v openssl >/dev/null 2>&1 || {
+	printf '%s\n' "openssl is required to generate installation secrets." >&2
+	exit 1
+}
+
+if [ -L "$environment_file" ]; then
+	printf '%s\n' "Refusing to write through symlink $environment_file." >&2
+	exit 1
+fi
+
+working_file=$(mktemp "$directory/.env.setup.XXXXXX")
+generated_keys=
+trap 'rm -f "$working_file"' EXIT HUP INT TERM
+
+if [ -f "$environment_file" ]; then
+	cp "$environment_file" "$working_file"
+else
+	cp "$example_file" "$working_file"
+fi
+chmod 600 "$working_file"
+
+for key in POSTGRES_PASSWORD HEPHAESTUS_SECURITY_ENCRYPTION_KEY HEPHAESTUS_AUTH_STATE_COOKIE_KEY WEBHOOK_SECRET; do
+	if [ "$(grep -c "^${key}=" "$working_file")" -gt 1 ]; then
+		printf 'Refusing duplicate %s assignments in %s.\n' "$key" "$environment_file" >&2
+		exit 1
+	fi
+done
+
+set_if_empty() {
+	key=$1
+	format=$2
+	if grep -q "^${key}=." "$working_file"; then
+		return
+	fi
+	case "$format" in
+		hex16) value=$(openssl rand -hex 16) || return 1 ;;
+		hex32) value=$(openssl rand -hex 32) || return 1 ;;
+		base64) value=$(openssl rand -base64 32 | tr -d '\n') || return 1 ;;
+	esac
+	if ! grep -q "^${key}=" "$working_file"; then
+		printf '%s=%s\n' "$key" "$value" >> "$working_file"
+		generated_keys="$generated_keys $key"
+	elif grep -q "^${key}=$" "$working_file"; then
+		temporary_file=$(mktemp "$directory/.env.value.XXXXXX")
+		while IFS= read -r line; do
+			if [ "$line" = "$key=" ]; then
+				printf '%s=%s\n' "$key" "$value"
+			else
+				printf '%s\n' "$line"
+			fi
+		done < "$working_file" > "$temporary_file"
-		while IFS= read -r line; do
-			if [ "$line" = "$key=" ]; then
-				printf '%s=%s\n' "$key" "$value"
-			else
-				printf '%s\n' "$line"
-			fi
-		done < "$working_file" > "$temporary_file"
+		while IFS= read -r line || [ -n "$line" ]; do
+			if [ "$line" = "$key=" ]; then
+				printf '%s=%s\n' "$key" "$value"
+			else
+				printf '%s\n' "$line"
+			fi
+		done < "$working_file" > "$temporary_file"
-		while IFS= read -r line; do
-			if [ "$line" = "$key=" ]; then
-				printf '%s=%s\n' "$key" "$value"
-			else
-				printf '%s\n' "$line"
-			fi
-		done < "$working_file" > "$temporary_file"
+		while IFS= read -r line || [ -n "$line" ]; do
+			if [ "$line" = "$key=" ]; then
+				printf '%s=%s\n' "$key" "$value"
+			else
+				printf '%s\n' "$line"
+			fi
+		done < "$working_file" > "$temporary_file"
+		chmod 600 "$temporary_file"
+		mv "$temporary_file" "$working_file"
+		generated_keys="$generated_keys $key"
+	fi
+}
+
+set_if_empty POSTGRES_PASSWORD hex16
+set_if_empty HEPHAESTUS_SECURITY_ENCRYPTION_KEY hex16
+set_if_empty HEPHAESTUS_AUTH_STATE_COOKIE_KEY base64
+set_if_empty WEBHOOK_SECRET hex32
+
+mv "$working_file" "$environment_file"
+
+for key in $generated_keys; do
+	printf 'Generated %s.\n' "$key"
+done
+
+printf '\nConfiguration written to %s. Generated values were not printed.\n' "$environment_file"
+printf '%s\n' 'Set APP_HOSTNAME, ACME_EMAIL, one OAuth provider, and HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS before starting Hephaestus.'
diff --git a/docs/admin/configuration-readiness.mdx b/docs/admin/configuration-readiness.mdx
@@ -0,0 +1,109 @@
+---
+title: Configuration readiness
+---
+
+# 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.webhook.secret` | `WEBHOOK_SECRET` |
+| `hephaestus.sync.nats.enabled` | `NATS_ENABLED` |
+| `hephaestus.sync.nats.server` | `NATS_SERVER` |
+| `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.
+
+## Credential encryption
+
+Set `hephaestus.security.encryption-key` to exactly 32 printable, non-space ASCII characters and keep it
+with the database backup. The supported self-host setup generates it. Do not change it on an existing
+installation.
+
+## 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. This check validates syntax and role consistency, not
+authentication, 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
+[Agent image digests](./agent-image-digests.md).
+
+## Sandbox isolation
+
+Set `SANDBOX_CONTAINER_RUNTIME=runsc` on workers after
+[installing and configuring gVisor](https://gvisor.dev/docs/user_guide/install/) 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.
diff --git a/docs/admin/install.mdx b/docs/admin/install.mdx
@@ -32,7 +32,8 @@ The stack you get:
 - **AI practice review adds real memory**: each concurrent review sandbox may use up to
   4 GiB. The default caps it at 1 concurrent sandbox; raise
   `SANDBOX_MAX_CONCURRENT` only with RAM to match.
-- 64-bit Linux with **Docker Engine ≥ 24** and **Docker Compose ≥ 2.24.4** (`docker compose version`), plus `git`.
+- 64-bit Linux with **Docker Engine ≥ 24** and **Docker Compose ≥ 2.24.4** (`docker compose version`),
+  plus `git` and `openssl`.
 - A **DNS A record** for your hostname pointing at the host, with ports **80 and 443**
   reachable from the internet (Let's Encrypt HTTP-01, OAuth callbacks, webhooks).
 - Outbound HTTPS to `ghcr.io` and `docker.io` (images — NATS and Traefik come from Docker Hub),
@@ -52,28 +53,28 @@ sudo git clone --depth 1 --branch "v$VERSION" \
   https://github.com/ls1intum/Hephaestus.git /opt/hephaestus
 sudo chown -R "$USER" /opt/hephaestus
 cd /opt/hephaestus/docker/self-host
-cp .env.example .env
+./setup.sh
 ```
 
-Everything below runs from `/opt/hephaestus/docker/self-host`. Once step 2 has filled in every
-required value, `docker compose config` renders the effective configuration — it is the quickest way
-to confirm a variable landed where you expected. Before then it exits with the first
-`required variable … is missing a value`, which is also how every other `docker compose` subcommand
-behaves in this directory; see [Troubleshooting](#troubleshooting).
+`setup.sh` creates or updates `.env` with mode `0600` and generates the database password,
+credential-encryption key, OAuth state-cookie key, and webhook secret. It does not replace non-empty
+values and never prints a secret.
+
+Everything below runs from `/opt/hephaestus/docker/self-host`. After step 2 supplies the remaining
+required values, `docker compose config` renders the effective configuration. Before then it exits
+at the first missing required variable, as does every other `docker compose` subcommand in this
+directory; see [Troubleshooting](#troubleshooting).
 
 ## 2. Configure `.env`
 
-Open `.env` and fill in every **REQUIRED** value. The short version:
+Open `.env` and fill in the remaining **REQUIRED** values. `setup.sh` manages the four internal
+secrets listed above; do not replace them manually.
 
 | Variable | What / how |
 | --- | --- |
 | `APP_HOSTNAME` | Your public hostname, e.g. `hephaestus.example.com` |
 | `IMAGE_TAG` | The same `$VERSION` you fetched above — an exact release, never `latest` |
 | `ACME_EMAIL` | Let's Encrypt expiry notices |
-| `POSTGRES_PASSWORD` | `openssl rand -hex 16` |
-| `HEPHAESTUS_SECURITY_ENCRYPTION_KEY` | `openssl rand -base64 24 \| cut -c1-32` — exactly 32 chars (see the warning below) |
-| `HEPHAESTUS_AUTH_STATE_COOKIE_KEY` | `openssl rand -base64 32` |
-| `WEBHOOK_SECRET` | `openssl rand -hex 32` — you'll enter the same value on GitHub later |
 | `GH_OAUTH_CLIENT_ID` / `_SECRET` | From step 3 |
 | `HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS` | From step 4 — set it **before** first boot |
 
@@ -83,6 +84,11 @@ signing key. If you lose or change it, those tokens become unreadable and all se
 invalidate. Store it as carefully as the database itself, and never change it after first boot.
 :::
 
+The other generated values also have lifecycle consequences: changing the database password does not
+update an initialized PostgreSQL volume, rotating the state-cookie key invalidates OAuth flows already
+in progress, and rotating the webhook secret requires the same change at every configured provider.
+Back up `.env` with the database as described in [Backup & Restore](./backup-restore).
+
 ## 3. Create the GitHub OAuth App (login — mandatory)
 
 Without a login provider the instance boots but shows **no sign-in button**. GitHub login
@@ -203,7 +209,7 @@ a backup instead. Set up [Backup & Restore](./backup-restore) **before** you hav
 | Symptom | Cause / fix |
 | --- | --- |
 | `application-server` exits: *ProxyTrustGuard* | `HEPHAESTUS_TRUSTED_PROXIES` is blank. The compose default is non-blank, so this means you overrode it to empty — unset your override, or set it to match `reverse-proxy`'s IP if you changed the network. |
-| Exits: encryption-key length error | `HEPHAESTUS_SECURITY_ENCRYPTION_KEY` must be exactly 32 characters — regenerate with the command above. |
+| Exits: encryption-key length error | `HEPHAESTUS_SECURITY_ENCRYPTION_KEY` must be exactly 32 printable, non-space ASCII characters. Restore the original key for an existing database. On a new installation, clear the invalid value and rerun `./setup.sh`. |
 | Login page has no sign-in button | No login provider configured: both `GH_OAUTH_CLIENT_ID` **and** `_SECRET` must be non-empty (a half-filled pair is skipped and logged at ERROR). |
 | OAuth redirect loop / cookie never sticks | A proxy in front of Traefik is injecting a `Domain=` attribute on cookies, which browsers reject for `__Host-` cookies. Serve the stack directly on ports 80/443. |
 | Signed in but not admin | `HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS` didn't match. On the account's **first** login the server logs (INFO) the exact `provider subject username` it saw — copy that into the allowlist and restart. (For an account that already existed, check that log line from its first sign-in, or use the numeric id.) |

diff --git a/docs/admin/production-setup.mdx b/docs/admin/production-setup.mdx
@@ -34,11 +34,13 @@ consists of:
 
 ## Base environment variables
 
-The required secrets — `HEPHAESTUS_SECURITY_ENCRYPTION_KEY`, `HEPHAESTUS_AUTH_STATE_COOKIE_KEY`,
-`WEBHOOK_SECRET`, `POSTGRES_PASSWORD`, the GitHub OAuth pair, and
-`HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS` — are documented once, on the
-[Install guide](./install#2-configure-env), along with how to generate each and the warning about
-never changing the encryption key. Everything there applies to this stack too.
+The required base values — `HEPHAESTUS_SECURITY_ENCRYPTION_KEY`,
+`HEPHAESTUS_AUTH_STATE_COOKIE_KEY`, `WEBHOOK_SECRET`, `POSTGRES_PASSWORD`, the GitHub OAuth pair, and
+`HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS` — are documented once in the
+[Install guide](./install#2-configure-env), along with their lifecycle constraints. The self-host
+installer generates its internal secrets; operators of the reference deployment must provision
+equivalent values through its protected secret-management system. The warning about never changing
+the encryption key applies to both stacks.
 
 These variables exist only in the reference deployment, so they live here:
 

diff --git a/docs/sidebars.admin.ts b/docs/sidebars.admin.ts
@@ -20,6 +20,7 @@ const sidebars: SidebarsConfig = {
 		{ type: "doc", id: "production-setup", label: "Integrations & Reference Deployment" },
 		{ type: "doc", id: "compatibility-policy", label: "Compatibility Policy" },
 		{ type: "doc", id: "runtime-roles", label: "Runtime Roles" },
+		{ type: "doc", id: "configuration-readiness", label: "Configuration Readiness" },
 		{ type: "doc", id: "agent-image-digests", label: "Agent image digests" },
 		{ type: "doc", id: "buildpacks-cds-decision", label: "Server image build (Buildpacks + CDS)" },
 		{ type: "doc", id: "legal-pages", label: "Legal Pages" },