Environment variables

This is the canonical list of every environment variable KilnCMS reads, with a pointer to the line that reads each one. It is long because the surface is genuinely large — but almost none of it is something you have to decide.

Read it in this order:

1. Required (3) — the only variables without which a production release refuses to start. There are three.
2. Common (10) — not required, but what a real deployment usually sets. A short list, with a one-line reason for each.
3. Everything else — the other 147, grouped by the feature they configure. Every one is optional and has a default, so you can skip a whole section by not using the feature it configures.

Variables are read at boot by config/runtime.exs, which executes for releases after compilation and before the system starts. That file is an index: the configuration itself lives in per-concern fragments under config/runtime/, and the "Where it's read" column points into whichever one holds the read.

Scope. Most variables only take effect when config_env() == :prod (i.e. in a mix release / MIX_ENV=prod build). In dev and test, sensible defaults from config/dev.exs and config/test.exs are used instead, so you do not need to set these locally. The exceptions — read in every environment, because they sit outside the config_env() == :prod fragments — are:

PHX_SERVER, PORT, CSP_IMG_SRC, UNSPLASH_ACCESS_KEY, CORS_ORIGINS, KILN_READING_TIME_WPM, VISUAL_EDITING_ENABLED, the KILN_API_CACHE* and KILN_CDN_PURGE_* groups, KILN_LINK_CHECK_CRON / KILN_LINK_CHECK_USER_AGENT, KILN_TASK_DIGEST_CRON, KILN_OBAN_RESCUE_AFTER_MINUTES, KILN_OCCURRENCE_SWEEP_CRON / KILN_OCCURRENCE_BACKFILL_ON_BOOT, PRESENTATION_PREVIEW_URL, the KILN_UPDATE_* group (plus KILN_PIN_PATH), KILN_ANALYTICS_REFERRERS, KILN_ANALYTICS_LOW_COUNT_THRESHOLD, SENTRY_DSN / SENTRY_ENV / RELEASE_VSN, and the OTEL_* group.

Several more are read in every environment except :test, where they are skipped so the suite cannot depend on a developer's exported shell: KILN_ENV_LABEL / KILN_ENV_COLOR, EMBED_ORIGINS / EMBED_ORIGINS_LOCKED, KILN_AUDIT_ANCHORS_ENABLED, KILN_AUDIT_ANCHOR_EVERY_WRITE, the KILN_GOVERNANCE_WITNESS* group (plus KILN_GOVERNANCE_CHECKPOINT_CRON), and the KILN_PROVENANCE_* group, and the KILN_DEMO_* group. MIX_TEST_PARTITION and KILN_STRICT_TEST are the reverse — test-only. KILN_ML is neither: it is read at build time, by mix.exs itself.

Required (3)

Exactly three variables stop a production boot. Nothing else in this document does: every other variable has a default, and a release that sets only these three starts and serves.

Those three are derived from the code rather than maintained by hand: they are the only raises a :prod evaluation of the runtime config reaches with nothing else set, and a test pins that. A handful more raise once you opt into the feature they belong to, which is a different promise: setting S3_BUCKET without S3_PUBLIC_BASE_URL, AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY raises, as does MAIL_MODE=smtp without SMTP_HOST, MAIL_MODE=direct without MAIL_FROM_EMAIL, and any MAIL_MODE that is neither. Leave the feature alone and none of them applies.

Common (10)

Not required — a release boots without every one of these — but these are the ones a real deployment usually sets, and the ones worth reading before you go looking through Everything else. Each links to its full row.

Everything else

The full surface, grouped by the feature it configures. Everything below is optional: unset means the feature is off or keeps the default named in its row.

server and networking

Note on ports. The public URL is hardcoded to port 443/https (config/runtime/prod/web.exs:223); the app itself listens on PORT. The expected topology is a TLS-terminating reverse proxy on 443 forwarding to the app on PORT. Public links (PUBLIC_BASE_URL) follow the same rule unless you set that variable.

background jobs (Oban)

API documentation (#567)

The OpenAPI 3 document and the Swagger UI explorer over it. Served in dev and test; off in a production build, for the reason GraphQL introspection is — since #330 the described surface includes the write routes, so the document is a complete machine-readable map of the mutation API. It grants nothing (the Ash policies and the API key's scope still enforce every route), but it removes the guesswork.

Disabled, both paths answer 404 rather than 403: a 403 confirms the route exists and is merely closed. The one exception is a request carrying an API key (Authorization: Bearer kiln_…): the OpenAPI document answers it, and so does GET /api/graphql/schema.graphql where introspection is off, so a client author can run codegen against their own production site. The explorer never does. The stock build's specs are also committed, at docs/api/ — see api.md.

API caching and CDN purge

Anonymous reads of JSON:API, GraphQL GET and /api/search are marked public with a body ETag, so a CDN in front of Kiln can answer them; any request carrying a credential is private, no-store (see api.md). Read in every environment.

multi-tenancy (#336)

One deployment can serve many organizations, each on its own host (the isolation model as a whole is in multi-tenancy.md). The request's Host picks the org: a subdomain of TENANT_BASE_HOST (acme.example.com → org acme), else an exact custom_domain on an org, else the default org. See KilnCMSWeb.Tenant.

What it covers. Everything the router serves, plus LiveView mounts and all three sockets — GraphQL (/ws/gql), visual editing (/ws/bridge) and collaborative editing (/ws/collab, since #655) — each resolving its tenant from its own connect URI and refusing rather than falling back. One thing sits outside it, and it performs no org-scoped reads:

• Static files, including /uploads under the local storage adapter. Both Plug.Static mounts run earlier in the endpoint and halt on a match, so an asset URL answers on any Host. Keys are unguessable UUIDs, and putting tenant resolution ahead of static would add two DB lookups to every asset request; treat media URLs as host-agnostic, as they would be behind a CDN.

What stays reachable. Two controllers are exempt, because both are deliberately host-independent and neither reads the ambient tenant:

• The liveness and readiness probes (/up, /ready), so a load balancer or orchestrator sending the container's IP as Host keeps getting a 200 — turning this on will not mark a healthy deployment unhealthy.
• The payment-provider webhook (POST /billing/webhooks/stripe), which arrives at whatever host the endpoint was registered with, is authorized by an HMAC over the raw body, and resolves its organization from the event payload.

The exemption keys on the controller, not on a path list, so it tracks the router.

Before creating a second organization (or setting TENANT_STRICT_HOST=true), confirm every host that must reach the app is accounted for: each org's subdomain or custom_domain, and the PHX_HOST apex itself (it resolves to the default org, and is never refused even if the database is briefly unreachable). Once strict matching is on, anything else gets a 404.

404 means "no such host"; a database outage gets a 503 (#341). A host that could not be looked up is a different answer from one that matches no org, and Kiln keeps them apart:

• With strict matching off — a single-org install under the default or under TENANT_STRICT_HOST=false — a failed lookup falls back to the default org exactly as an unmatched host does. Nothing is refused in this mode, including during an outage, which is what lets warm content keep being served from cache without a database (#341): tenant resolution runs in the endpoint, above the cache.
• With it on, an unresolvable host is still refused (falling back would serve the default org on an unrecognized host, which is what this setting exists to prevent), but as a plain-text 503 with retry-after, not a 404. The host may well exist; a 404 is what a CDN caches, an uptime monitor pages the tenant about, and a search engine deindexes on. The health-probe and webhook exemptions above apply to this refusal too.

The refusal no longer costs a query every time (#659). A refused request is halted before the router, and every rate limiter lives in a router pipeline — so turning this on originally took the path out of the :delivery ceiling and left one uncached organization lookup per request, metered by nothing. Unresolvable hosts are now cached as misses, in a cache of their own (KilnCMS.Cache.Hosts, one-minute negative TTL) so that a flood of invented hosts cannot evict hot published pages the way it would have in the shared content cache. A repeated flood costs one lookup per distinct host per minute rather than one per request; a flood of distinct hosts still costs a lookup each, which is the price of never refusing a host that does exist. Terminate unknown hosts at the proxy if that load matters. As a side effect, tenant resolution no longer evaporates when an editor saves a media item — it used to live in the cache that a content bust clears wholesale.

What the refusal reveals. An unknown host gets a plain-text 404; a known host with an unmatched path gets the branded HTML 404. The two are distinguishable, so a dictionary sweep of <candidate>.<base host> will enumerate which org slugs exist, and which custom_domains are configured. This is accepted rather than fixed: making them identical means either showing unknown hosts the branded page — the default-org leak this control exists to prevent — or degrading every tenant's real 404 to plain text, to hide names that are already public in DNS and in TLS certificates. If your tenant list is itself confidential, terminate unknown hosts at the proxy, where one uniform response covers both cases.

white-label branding (#48)

The instance-wide branding layer, beneath each site's own editor-managed SiteBranding row — a per-org row always wins, so these set the fallback every org inherits until it overrides them. Unset vars fall through to the stock KilnCMS defaults. All four are read only under :prod; for dev or test, set config :kiln_cms, :branding, … in a config file. See KilnCMS.Branding.

Unsplash (media library)

database TLS

object storage (S3-compatible)

Opt into the S3 storage adapter by setting S3_BUCKET. When it is set, S3_PUBLIC_BASE_URL, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY become required (the latter two raise via System.fetch_env!). See KilnCMS.Storage.S3 for per-provider hosts, and media-pipeline.md for the CDN deployment guide. A site admin can give their site its own bucket at /editor/site-storage (#1559); that site's new uploads then use it and none of these. See Per-site buckets.

Media objects are uploaded with Cache-Control: public, max-age=31536000, immutable — there is no env var for it, because storage keys are write-once UUIDs so a URL's bytes never change. If the CDN hostname differs from the site's origin, add it to CSP_IMG_SRC or the browser will block the images.

in-app backups (#484)

Read in production only. Every one of these is a variable scripts/backup.sh already reads, by the same name — the cron path and the in-app path are two front doors to one backup directory, and an operator who configured the script does not configure this separately. See backups.md.

The console's Backups page (/editor/backups, admin only) reads $BACKUP_DIR/manifest.json, which backup.sh all writes — so it reports on cron's backups, not only ones taken from the app.

The runtime image needs pg_dump. It installs postgresql-client-17, and the major version must match your Postgres server — pg_dump refuses to run against a newer one. Bump the pin in the Dockerfile alongside a server upgrade. Where the tools are absent, the console says so rather than failing at the point of use.

SSO (OpenID Connect, #331)

Only read when SSO was compiled in (config :kiln_cms, :sso_oidc, enabled: true — see docs/sso.md). All four are then required for the flow to work.

Where to get them. Register a confidential (server-side web) application at your identity provider — Entra ID, Okta, Keycloak, Auth0, Google Workspace, any OIDC-conformant IdP. It issues the client id and secret; you hand it OIDC_REDIRECT_URI as the permitted callback. Kiln authenticates with client_secret_basic, so the IdP must allow that token-endpoint auth method. OIDC_ISSUER is the provider's base URL — whatever serves <issuer>/.well-known/openid-configuration — and discovery supplies the rest, so there are no other endpoints to copy across.

outbound email

With none of these set, production uses the dev-only in-memory adapter: the app runs, but every delivery job fails in Oban and no email leaves. Opt into real delivery with MAIL_MODE (or, for back-compat, just SMTP_HOST, which implies MAIL_MODE=smtp). Direct mode is configured and verified from /editor/mail — see the operator guide docs/direct-email-delivery.md for the DNS requirements (SPF/DKIM/DMARC/PTR) and the big caveat: many cloud hosts block outbound port 25.

These variables set the deployment's relay. A site admin can send their site's mail through their own SMTP relay and From address instead, from /editor/site-mail (#1322), with no redeploy. That covers newsletters, form mail, notifications and automation emails. The relay set here stays in use for account mail (sign-in links, password resets), and for every site that hasn't set its own. A site's relay host may not be a private address. An internal relay belongs here, where the operator sets it.

search (Meilisearch)

Opt into the typo-tolerant search backend by setting MEILI_URL; otherwise Postgres full-text search is the only backend. Run mix kiln.meili.reindex once after enabling. See docs/meilisearch.md.

These variables set the deployment's instance. A site admin can index their site into their own Meilisearch instead, from /editor/site-search (#1558), with no redeploy; the instance set here stays in use for every site that hasn't set one. A site's instance must be HTTPS and may not be a private address. An internal instance belongs here, where the operator sets it.

search (chunked document embeddings)

Semantic search only (config :kiln_cms, KilnCMS.Search, semantic: true).

search relevance floor (#1936)

Runtime overrides for hybrid search's relevance floor, which is otherwise compiled config :kiln_cms, KilnCMS.Search — so a retune, or a model-swap window, is a restart rather than a deploy each way. Unset leaves the compiled value (or a project overlay's) in force; an unusable value keeps it too, and warns. See semantic-search-plan.md for what the floor does and how to measure it.

vector search scan (measurement runs)

How the semantic legs scan pgvector's HNSW indexes. Leave both unset on a deployment serving traffic — unset is what every release has always done (hnsw.iterative_scan = strict_order, pgvector's default ef_search of 40). They exist for a measurement replica: recall@k and MRR comparisons (mix kiln.search.eval, mix kiln.search.measure_floor) taken at the default ef_search carry approximate-recall noise, so measurement runs use ef_search 200 or exact. Read in every environment. Unlike every other variable in this document, an unusable value refuses to boot instead of keeping the default and warning: a typo that fell back to ef_search 40 would produce exactly the numbers the setting exists to exclude. Setting both is refused too. The search tasks take the same settings as --ef-search N / --exact for a local run, and print the mode in effect in their header. See KilnCMS.Search.VectorScan and semantic-search-plan.md.

AI-assisted SEO drafting

Opt in by setting SEO_MODEL. Unset, the editor's suggest control never renders and no content leaves the deployment — the deterministic SEO analysis and score are unaffected either way. Like the other variables on this page these are read in the production branch of runtime.exs; for dev or test, set config :kiln_cms, KilnCMS.Seo, … in a config file. Prefer an on-prem model (ollama:/vllm:); a hosted provider is announced at boot and in the editor, and should be added to your DPA's subprocessor list. See docs/seo.md.

These AI variables (this section and the two after it) are the operator's layer. A site admin can give their site its own provider, API key and models at /editor/site-ai (#1557); that site then uses its own and none of these. See Per-site provider.

AI block assist in the editor

The body-copy twin of SEO_MODEL, and a separate switch: this one sends a block's prose and the editor's typed instruction on each request, and returns text bound for the page body. Setting SEO_MODEL alone leaves it off and the per-block "AI assist" control never renders. Same on-prem preference and same boot warning for a hosted provider. See docs/ai-assist.md.

generated answers for /api/ask

The third AI switch, and the one to think hardest about, because it is the only one a stranger can trigger: /api/ask is a public, anonymous endpoint. Unset, it stays what it is by default — retrieval-only, returning cited published passages, "answer": null and "generation": "disabled" — and nothing leaves the deployment.

Only published, world-readable content is ever retrieved, so no draft can reach the model whatever the setting. Generation carries its own rate-limit buckets on top of the pipeline's per-IP limiter, keyed on the client address for anonymous callers; an exhausted bucket degrades to retrieval-only rather than refusing the request, and says so — "generation": "rate_limited" with a retry_after, so a client can tell a throttle from a switch. Same on-prem preference and same boot warning for a hosted provider. See docs/rag.md.

rich embed cards (oEmbed, #489)

Off by default, and enabling it is egress: the server makes an outbound HTTPS request when an editor saves a document containing an embed block whose URL one of the curated providers claims. With it off, an embed renders exactly as it always has — a bare figure for anything but YouTube and Vimeo, which are framed without any network call.

Requests only ever go to the provider endpoints listed in KilnCMS.OEmbed.Provider — never to a URL discovered from content — and through the address-pinned, size-capped KilnCMS.SafeFetch. The provider's html is discarded rather than sanitized; only title, author, provider name and a thumbnail are stored, and the thumbnail must be on that provider's own CDN.

outbound link checking (#474)

Neither of these switches the feature on. Outbound checking is opt-in per site, in the console at /editor/links, because it is the site's content that decides which third parties get requested — see docs/link-checking.md. An unconfigured deployment with no site opted in makes no outbound requests at all, so the sweep is scheduled everywhere by default.

Internal links need none of this: they are checked by a database query in the editor's advisory panel, with no switch and no schedule.

editorial tasks (#501)

Safe to leave scheduled everywhere: with no tasks assigned in any org, the digest sweep enqueues nothing.

Web Push notifications (#628)

Unset ⇒ push is off for every site that hasn't generated its own key: /editor/settings never offers the toggle there and nothing is sent. A site admin can instead generate a key pair for their site at /editor/site-push (#1560), with no variables and no redeploy. These variables stay the default for every site without its own pair, and a device subscribed with them keeps them after its site generates one. Generate a pair with mix kiln.vapid.gen (the same format npx web-push generate-vapid-keys emits, so an existing pair carries over).

Rotating the pair invalidates every live subscription — the push service answers 403, the row is pruned, and reviewers must re-enable notifications on each device. Notifications never carry draft content; see KilnCMS.Push.

events, the "what's on" index (#766)

Safe to leave scheduled everywhere: a site with no event-shaped content does one indexed probe per content type and matches nothing. See docs/events.md.

error tracking (Sentry)

Enabled in any environment only when SENTRY_DSN is set; otherwise every Sentry capture is a no-op. See docs/observability.md.

distributed tracing (OpenTelemetry)

Enabled only when OTEL_EXPORTER_OTLP_ENDPOINT is set, which flips the :otel_enabled flag and points the OTLP exporter at the collector. See docs/observability.md.

metrics exporter (Prometheus, #1362)

Off by default. When KILN_METRICS_ENABLED is on, GET /metrics is served in the Prometheus text format on a listener of its own. It is never a route on the public endpoint. With the exporter off, no port is opened and nothing records the metrics. See docs/observability.md for the exposure options and a scrape config.

tamper-evident history & content signing (#356, #340)

Every publish folds the document's version chain into a canonical hash and records it append-only in history_anchors, RSA-signed when a signing key is configured. See editorial-consent.md and KilnCMS.Governance.Chain.

Rotating the signing key. Verification resolves the key named by each signature's key_id, so pre-rotation anchors and manifests keep verifying — once the outgoing key's public half is registered (KILN_PROVENANCE_RETIRED_KEY_FILES, or retired_keys in source). Register it before destroying the outgoing private half: until it is registered, those signatures resolve to {:error, {:unknown_key_id, …}}, and with the private half gone there is no way to re-derive the public one. Order matters — export the public half, point the var at it, restart, confirm an old anchor still verifies, and only then destroy the private key. See KilnCMS.Provenance.KeyRegistry.

governance checkpoint witness (#666)

Anchors make a document's history tamper-evident against everything except truncation: delete its newest anchors and the surviving prefix still verifies, because nothing inside the document says how many there were. A checkpoint is the statement from outside — a signed, org-wide commitment to every document's head anchor, minted on a schedule and published to a sink the database credentials do not own. See KilnCMS.Governance.Checkpoint and KilnCMS.Governance.Witness.

Publishing is only half of it. A checkpoint nobody reads back is a file. mix kiln.audit.checkpoint --audit re-fetches every published checkpoint and diffs it against the database row, so a deleted or rewritten chain_checkpoints is visible. Run it from a host the application does not control, on credentials that can read the sink and not write it — an audit run by the same role that writes the checkpoints only establishes that a system agrees with itself.

Unsigned deployments. With no KILN_PROVENANCE_PRIVATE_KEY, a checkpoint's root and links are ordinary columns an attacker can recompute, and every verdict is floored to :unsigned regardless. The structural checks still run and still report, so a truncation is still named — but treat it as advisory: it raises the cost of a forgery, it does not attest anything. Configure a signing key before relying on any of this.

upstream update check

The admin system page (/editor/system) reports whether a newer Kiln release exists. The check is made only when an admin opens the page, and asks in two legs (#1877): first the release feed on kilncms.dev — the public published-entries API every Kiln serves, filtered to its release entries — and, only if that fails in any way, the GitHub releases API. An outage of kilncms.dev therefore only changes where the answer comes from. Results are cached for 24 hours (15 minutes when both legs failed) and manual re-checks are floored at one per minute. See docs/releasing.md and Kiln.Updates.

What is sent. Each request is an unauthenticated GET with a bare KilnCMS user-agent: no version, no host name, no instance identifier, no cookie or credential. The feed request's only query parameters are its fixed type filter, field list and page size (?filter[type_name]=release&fields[entry]=custom_fields&page[limit]=100); the GitHub request has none. Nothing about this deployment is disclosed beyond the IP address the request comes from.

kilncms.dev keeps no client IPs for the feed route. The application does not log the client address for that route, and keeps it off any error report (KilnCMSWeb.SentryScrubber); the reverse proxy in front of kilncms.dev is configured not to log it either. GitHub's own logging of the fallback request is GitHub's.

To opt out, set KILN_UPDATE_CHECK=false: no request is made to either service, and the page reports the running version and the update command without the comparison. To keep the check but skip kilncms.dev, set KILN_UPDATE_FEED_URL=false (GitHub only).

This is the only outbound integration that is on by default. Unlike Meilisearch, S3, Unsplash and mail, it needs no credential to work, so there is no unset-secret that implicitly disables it — set KILN_UPDATE_CHECK=false if your deployment must make no third-party requests at all.

If you run a fork, set KILN_UPDATE_REPO. The default compares this build against The-Verscienta/kiln_cms, which for a fork is an answer about someone else's code — and the failure is silent in the direction that matters: a fork ahead of upstream compares as newer, so the page reports "Up to date" indefinitely and the fork's own security releases never surface.

Setting KILN_UPDATE_REPO (to anything but the canonical repo) or KILN_UPDATE_RELEASES_URL also stops the kilncms.dev feed from being asked, since it describes upstream's releases: a fork or an internal mirror goes straight to its own endpoint. A fork that publishes its own release entries on its own Kiln site opts back in by setting KILN_UPDATE_FEED_URL to that site's feed.

GIT_SHA and BUILD_DATE are Docker build args, not runtime variables — the Dockerfile records them as KILN_GIT_SHA / KILN_BUILD_DATE so a running instance can name the commit it was built from. Without GIT_SHA it takes the SOURCE_COMMIT build arg, which Coolify passes when the app's Include Source Commit in Build setting is on. Omitting them is harmless; the page then reports the version alone.

referrer attribution (#619)

Coarse "where did readers come from" categories (direct / internal / search / social / other) per content item per UTC day — never a raw referrer URL or host. Off by default; enabling requires no rebuild. See docs/advanced-analytics-plan.md and docs/data-flows.md.

environment indicator

A coloured strip across the top of every console page naming this deployment (#469). A scrubbed staging clone keeps production's content and branding, so the two consoles are otherwise byte-for-byte identical — which is what invites "I edited the wrong environment".

Unset means no strip, so production stays clean with nothing configured. It is the environment you recognise by the absence of a label; staging and development are the ones that set these.

mix kiln.staging.scrub and scripts/staging.sh up both close with a reminder to set this. Neither can set it: the scrub runs as a throwaway process against a remote DATABASE_URL, not inside the application that will serve the clone.

A demo deployment (below) is labelled demo when KILN_ENV_LABEL is unset, and its strip also says when the next reset is due.

demo mode

A public "try the editor" instance that resets to a golden snapshot on a schedule. Hard off by default. Every reset also refuses unless the database name and PHX_HOST both contain demo and the snapshot was dumped from a demo database, and none of those checks can be overridden. Demo mode also makes mail inert (logged, not delivered) and switches federation off. See demo-mode.md.

seeding and staging

Not read at boot: these are consumed by a seed script and by the staging-scrub task, so they matter only for the command that reads them.

See staging-environments.md for the full clone → scrub → serve procedure.

Test / CI only

These are read by config/test.exs and config/e2e.exs and are not relevant to production.

How values are parsed

The shared rules behind the tables above — worth reading once, and the reason a mistyped flag can no longer flip anything in either direction.

Boolean variables

Every boolean variable in this document is parsed by one shared function, KilnCMS.Config.Env, so the rules below hold for all of them (PHX_SERVER is a partial exception — see its row):

• Accepted spellings. true / 1 / yes / on and false / 0 / no / off. Values are trimmed and lower-cased first, so TRUE, On and " true " all work.
• Unset or blank (FOO=, a common .env and --env-file artifact) means the variable was not set — the default in the table applies.
• Anything else keeps the default and warns. A misspelling is never interpreted — it cannot flip a flag in either direction. For the switches that default to on (DATABASE_SSL, SMTP_TLS, SMTP_TLS_VERIFY) that means a typo can no longer turn TLS off, which is the whole point of #606. For a switch that defaults to off, the flip side holds: a typo leaves it off, so if you set KILN_AUDIT_ANCHOR_EVERY_WRITE to turn signing on, the warning is the only signal that it didn't take.

Where that warning goes

Two places, because one of them is not enough (#634):

• stderr, at boot. Config providers run before Logger exists, so this is all that is available at the moment the value is read. In a release it lands in container stdout — docker logs — and is forwarded nowhere. If it scrolls past during a deploy it is gone.
• Logger, once the application is up, at warning level. Every unrecognized read is carried out of config/runtime.exs in :kiln_cms, :config_warnings and replayed as soon as observability is attached, so it goes through the normal logging pipeline — formatted, timestamped, and picked up by whatever collects the application's output.
• Sentry, as a warning-level message, when SENTRY_DSN is set. This is reported explicitly rather than left to the log line: Sentry's logger handler runs at level: :error with capture_log_messages: false, so a Logger.warning never reaches it. Issues are grouped per variable, so a flag that stays misspelled is one issue rather than a new one on every restart.

Only variables that hold a flag, a count, or a short constrained value like an enum spelling or a colour go through this. Nothing here echoes a credential; a variable carrying a secret is read elsewhere and its value is never logged.

Until #607 each variable had its own parser, and two of them matched the raw string: DATABASE_SSL=True silently gave you a plaintext Postgres connection (#606), and VISUAL_EDITING_ENABLED=False left the bridge on.

Count variables

The variables that hold a positive integer — KILN_READING_TIME_WPM, KILN_API_CACHE_MAX_AGE, KILN_API_CACHE_SWR, KILN_ANALYTICS_LOW_COUNT_THRESHOLD, KILN_EXPERIMENTS_STICKY_DAYS, BACKUP_KEEP_DAYS and BACKUP_STALE_AFTER_HOURS — go through the same module, as Env.positive_integer/1 (#1009). Before that each had hand-rolled its own Integer.parse, its own positivity check and its own warning.

• Unset or blank (including whitespace-only) means the variable was not set, exactly as for a flag — the default in the table applies, silently.
• Zero and negatives are refused, not read literally. Every one of these is a rate, a window or a retention, where 0 reads as "never" or "delete everything" rather than as "unset": BACKUP_KEEP_DAYS=0 taken at face value would delete the backup it had just taken.
• A partly-numeric value is refused, not truncated. BACKUP_KEEP_DAYS=7 days keeps the default rather than quietly becoming 7 — the operator meant a week and would otherwise never learn the unit was wrong.
• Anything above 2147483647 is refused (#1091). Elixir integers have no upper bound, so without this a digit slip was accepted where a letter slip warned — BACKUP_KEEP_DAYS=144444444444444 parsed cleanly into a four-billion-year retention. The ceiling is not a claim about a sensible value; every real one here is smaller by orders of magnitude, so what it catches is a typo.
• Anything refused keeps the default and warns, through all three sinks above. The count case is what #1009 added to that replay: the hand-rolled parsers wrote to stderr and stopped there, so a mistyped count reached neither Logger nor Sentry. The replayed line names the shape it wanted — a count is told to write a positive integer, not offered the boolean spellings.

Fractional and list variables

The relevance-floor variables (#1936) go through the same module, on the same terms: unset or blank means unset, anything refused keeps the default and warns through all three sinks, and the warning names the shape wanted.

• Env.float_in/4 reads a number within stated bounds — SEARCH_SEMANTIC_MAX_DISTANCE in [0, 2], SEARCH_KEYWORD_ANY_IDF_COVERAGE in (0, 1]. Unlike a count, zero is a value where the bounds allow it: a floor of 0.0 is the model-swap setting. Out-of-range values (3.5 for 0.35) and partly-numeric ones (0.35 cosine) are refused, not clamped or truncated.
• Env.list_of/3 reads a comma-separated list of known names — SEARCH_SEMANTIC_FLOOR_LEGS. One unknown name refuses the whole value rather than being dropped, as does a list missing a required name, so a typo can never leave the floor judging less than the operator wrote.

Compile-time application config (not environment variables)

Every variable above is read from the process environment when its config file is evaluated — almost all of them by config/runtime.exs, at boot. The two keys below are not environment variables at all. They are Application.compile_env/3 reads, the same mechanism :secure_session_cookie uses, because KilnCMSWeb.Endpoint's @session_options is a module attribute: it is fixed when the endpoint compiles, not when it starts (see KilnCMSWeb.SessionCookie). Exporting a shell variable at boot changes nothing.

A downstream deployment sets them in its overlay's config/project.exs, which config/config.exs imports last so an overlay can override the core's config:

config :kiln_cms,
  session_signing_salt: "…",
  session_encryption_salt: "…"

Both must be a non-empty string, and anything else fails the build. For the encryption salt that is not pedantry: Plug.Session.COOKIE reads a nil :encryption_salt as "sign, don't encrypt", with no error or warning, so the session's contents would become readable by anyone holding the cookie. The likeliest way to get a nil is to wire the key to System.get_env/1 in config/project.exs: a release is compiled in its own build stage, where that variable is usually not set, so a hardcoded value is the safer choice here.

A third public salt of the same family, live_view: [signing_salt: …] on the endpoint in config/config.exs, is not compile-time. It is endpoint config read when the endpoint starts, so config/project.exs could always override it with no code change. It signs LiveView session tokens, not the session cookie.