Configuration and secrets

The same project directory runs everywhere. What differs between your laptop, staging and production is the environment the engine starts in: engine.environment and the variables your config/engine.yaml interpolates. Configuration files are committed to git; secrets never are.

A production-ready engine.yamlCopy Anchor Link

This is the shape most deployments start from. Every value that differs per environment is a variable, and every secret is a bare ${VAR}:

engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}

server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}
  trusted_proxies: ["172.30.0.0/24"]   # the range your reverse proxy connects from
  security:
    signing_key: ${SIGNING_KEY}

database:
  url: ${DATABASE_URL}

logging:
  format: ${LOG_FORMAT:-json}

storage:
  driver: filesystem
  filesystem:
    root: ./storage

mail:
  driver: smtp
  from: "Visit Example <hello@example.org>"
  smtp:
    host: ${SMTP_HOST}
    port: 587
    username: ${SMTP_USERNAME}
    password: ${SMTP_PASSWORD}
    tls: starttls

Check it the way production will read it, without a database:

ENVIRONMENT=production engine-dmo check --no-db

check --no-db accepts an unset variable in a secret path, so CI and an image build can check the project without the deployment’s secrets. Every other unset variable is still an error.

EnvironmentsCopy Anchor Link

engine.environment is development (the default), staging or production. Any other value is an error.

Never run serve --dev in production: it reloads templates from disk on every request and starts the extensions’ development servers. Set ENVIRONMENT=production on every production process, including the one-off migrate up and schema apply steps, so they read the configuration the server will.

What production refusesCopy Anchor Link

In production the engine refuses at boot (and engine-dmo check reports) each of these:

engine-dmo check adds the mail rules, which a booting engine does not repeat:

Production also warns (it does not refuse) about auth.staff.local.breach_check: off, template.strict: true, dev.authoring (it has no effect), admin.theme.contrast_check: warn, a plain http S3 endpoint and a plain http OTLP endpoint on a public host.

Environment variables in configurationCopy Anchor Link

The engine reads no fixed environment variables for its configuration. It reads the variables your engine.yaml (and the other configuration files) name:

Interpolation happens in values only, never in keys, and only in string-typed settings. A boolean or a number cannot come from a variable: require_mfa: ${REQUIRE_MFA} does not load. Where a setting must change per environment and is not a string, keep it the same everywhere or use a separate configuration directory with --config.

Several interpolations may be combined in one string, such as base_url: https://${PUBLIC_HOST}, except in secret paths (below). For a connection string assembled from parts, assemble it in the environment (Compose and most orchestrators can) and pass the whole string as DATABASE_URL.

The engine does not read .env files. Your shell, process manager, container runtime or orchestrator sets the variables. Environment variables lists the names the starter project and the examples use.

The secret ruleCopy Anchor Link

A secret path must be exactly one bare interpolation, ${VAR}, with no default and nothing around it. A literal value, or ${VAR:-something}, is an error that names the file, line and column:

config/engine.yaml:12:18: server.security.signing_key is a secret and must be an environment interpolation, not a literal
      = write signing_key: ${SIGNING_KEY} and set the variable in the environment

The secret paths in engine.yaml:

Other files hold secrets under the same rule: a headless site’s frontend webhook secret in site.yaml (at least 16 characters), and stripe.secret_key and stripe.webhook_secret in config/paidlistings.yaml (engine-dmo only). A plugin’s env in plugins.yaml gets nothing of the engine’s own environment; a variable whose name looks like a credential (a key, token, secret or password) must be written as an interpolation there.

Secrets in developmentCopy Anchor Link

A secret path takes no default, so adding signing_key: ${SIGNING_KEY} (or any other secret) for production makes SIGNING_KEY required on every machine that loads the configuration, your laptop and CI included. check --no-db, describe and the dev verbs accept it unset; config validate, seed verify, new, render, serve and the rest refuse with environment variable SIGNING_KEY is not set. Set it in development to the empty string (the engine then derives a development key from the database URL, as when the key is absent) or to 32 or more random characters. A value of 1 to 31 characters is refused. Commands and the environment lists which commands need what.

A secret whose variable is set to the empty string is treated as not configured. That is how a project runs a Meilisearch server with no key: write api_key: ${MEILISEARCH_API_KEY} and set MEILISEARCH_API_KEY= (empty).

Where secrets showCopy Anchor Link

Secrets are redacted wherever configuration is printed: engine-dmo config render prints [redacted] for every secret path, engine-dmo doctor reports the database as host and name only, and a recorded error that happens to quote a configured secret is scrubbed before it is stored.

engine-dmo config render          # the fully resolved engine.yaml, defaults included, secrets redacted
engine-dmo config render --json   # the same as JSON
engine-dmo config validate        # engine.yaml alone, no database

Generating and rotating keysCopy Anchor Link

Generate each key with a cryptographic random source:

openssl rand -base64 48

Every replica of an install must have the same signing_key; replicas with different keys reject each other’s forms and sessions.

RelatedCopy Anchor Link

• engine.yaml reference: every key, its type and default.
• Environment variables: the variables the engine itself reads and sets.
• Container images: passing the environment to a container.