Configuration System

Status: Current as of 2026-04-18 (repo commit 06d84cb). Audience: New contributors setting up a dev environment; ops engineer rotating secrets; BfArM reviewer (security classification).

This document enumerates every environment variable across the three fragJulia runtimes, flags .env.example gaps, and classifies each secret by exposure scope.

1. Runtimes at a glance

Cron jobs: apps/web/vercel.json defines one — /api/chat/cleanup at 0 3 * * * UTC, guarded by CRON_SECRET.

2. Web (Vercel) — 22 vars in apps/web/.env.example

Exposure legend:

• 🔒 server-only — never reach the browser
• 🌐 client-exposed — prefixed NEXT_PUBLIC_*, visible in client bundle

Supabase (4)

Site URLs (2 + 1 optional)

Stripe (4)

Resend (1)

LiveKit — web caller (3)

Knotencheck test mode (2)

Security note: this pair intentionally lets a test UI bypass auth. Do not enable in a production-public environment. Consider gating on NODE_ENV !== 'production'.

Upstash Redis (rate limits) (2)

Security (2)

Known gaps (still missing from .env.example as of 2026-04-18)

• Turnstile (planned in #358): TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY
• Bedrock (planned in #358): AWS_REGION=eu-central-1 + access via IAM role for web runtime, or explicit AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY if not using instance role
• OpenAI (used today): OPENAI_API_KEY is implicit (AI SDK reads it from env) but not documented in .env.example — fix.

3. Voice (EC2) — 5 vars in voice/.env.example

Live file: /root/knotencheck-voice.env on the EC2 host. Committed example: voice/.env.example.

Hardcoded in voice/docker-compose.yml (not env-var driven)

• LIVEKIT_URL=ws://localhost:7880
• LLAMA_GUARD_ENDPOINT=http://localhost:8000/v1
• VOXTRAL_LOCAL_ENDPOINT=http://localhost:8001/v1
• FASTER_WHISPER_MODEL_PATH=/models/faster-whisper-large-v3
• NVIDIA_VISIBLE_DEVICES=all

If you move off host networking or relocate model files, these move into env.

Bedrock access

No env var — the voice-agent container assumes the EC2 instance's IAM role has bedrock:InvokeModel on eu-central-1. Document IAM role name + policy when BfArM reviewer asks.

Caddy / TLS

Cert renewal state in the caddy_data named volume (see docker-compose). No env vars.

4. Mobile (Expo / EAS) — 3 vars per environment

Source: apps/mobile/eas.json. No .env.example file in apps/mobile/ — env is configured per-channel in eas.json and injected at build time by EAS.

Note: EXPO_PUBLIC_SUPABASE_ANON_KEY is not in eas.json. Either consumed from a separate secrets source (EAS Secrets) or missing. Verify with native client before shipping next mobile release.

iOS / Android identifiers (in app.json, not env)

• Bundle identifier: de.fragjulia.app
• Expo scheme: fragjulia://
• Microphone usage string (German, DSGVO-relevant)

Submit credentials (in eas.json.submit.production.ios)

All REPLACE_WITH_* placeholders as of 2026-04-18:

• appleId, ascAppId, appleTeamId — fill before first store submission

5. Cron

Only one, defined in apps/web/vercel.json:

{
  "crons": [
    { "path": "/api/chat/cleanup", "schedule": "0 3 * * *" }
  ]
}

• Schedule: 03:00 UTC daily
• Guard: route handler checks authorization: Bearer ${CRON_SECRET} header (Vercel sets this automatically when invoking scheduled cron)
• Purpose: prune old chat messages past tier-specific retention (7 days for free, unlimited for plus/premium)

6. Security classification summary

Rules of thumb:

• Anything NEXT_PUBLIC_* ends up in the JS bundle. Never put secrets there.
• Anything EXPO_PUBLIC_* ends up in the RN bundle + OTA update payloads. Same rule.
• Keep Stripe price IDs as server-only — they're not secrets cryptographically but moving them client-side makes price changes much harder to revert.

7. Gaps to fix (tracked here, should become follow-up issues)

1. Mobile .env.example missing. Create apps/mobile/.env.example even if most env lives in eas.json — documents the shape of EAS secrets.
2. OPENAI_API_KEY undocumented. Present in production (chat route uses it), missing from .env.example. Adds onboarding friction.
3. SUPABASE_JWT_SECRET potentially dead. No obvious consumer — verify then either remove or document its use.
4. Turnstile vars planned (#358) — must land in .env.example on same PR that introduces the runtime dependency.
5. Voice .env.example lacks Bedrock config notes. Even if the live path uses IAM roles, document the expected IAM policy + fallback AWS_* vars for local dev.
6. EAS submit placeholders. appleId / ascAppId / appleTeamId — fill before first App Store submission.

8. How to rotate a secret (runbook)

1. Generate the new value (platform-specific — Stripe dashboard, Supabase settings, openssl rand -base64 32 for HMAC-like)
2. Update Vercel project settings (all environments: production, preview, development) — NOT .env.example
3. For voice (EC2): edit /root/knotencheck-voice.env, restart voice-agent container (docker compose restart voice-agent)
4. For mobile: update EAS Secret via eas secret:create or web UI; trigger a new build
5. Log the rotation in whatever audit path applies (future: audit.config_rotation event — see audit-system)
6. Revoke the previous value at the provider only after confirming the new one works in each environment

9. Related

Changelog

• 2026-04-18 — Initial version. Counts differ from bubbly-bubbling-quilt.md §2: web has 22 vars (quilt said 30+), voice has 5 (quilt said 8), mobile has 3 per EAS channel (quilt said 5). Turnstile still absent, OPENAI_API_KEY still undocumented. Single cron confirmed at 03:00 UTC.