Secrets and environment variables

String values in rdock.yaml can refer to environment variables and files. That keeps passwords, tokens and keys out of the configuration file, so the file can be committed to version control and shared.

What you need

The secret as a file, for example a Docker or Compose secret, a Kubernetes secret volume or a file readable only by the rdock user; or an environment variable of the ReverseDock process.

The three forms

Reference	Replaced by
`${NAME}`	The environment variable `NAME`.
`${env:NAME}`	The same, written explicitly.
`${file:/absolute/path}`	The contents of the file, with one trailing newline removed.

The path of a file: reference must be absolute. The file may hold at most 64 KiB of UTF-8 text.
A variable that is not set, or a file that cannot be read, is an error that names the configuration path where the reference appears. Nothing falls back to an empty value.
Text that a reference produced is never expanded again, so a secret that happens to contain ${ cannot pull in other values.
$${ writes a literal ${.
References work in string values, such as hosts, addresses, header values and tokens.

The configuration

This route sends an API key to its backend in a request header. The key is read from a file:

listeners:
  web:       { address: ":80" }
  websecure: { address: ":443", tls: {} }

certificates:
  example:
    cert_file: /etc/rdock/certs/example.com.pem
    key_file: /etc/rdock/certs/example.com.key
    key_password: "${file:/run/secrets/example_key_password}"

routes:
  app:
    match: "Host(`app.example.com`)"
    service: app
    middlewares: [backend-key]

middlewares:
  backend-key:
    type: headers
    request:
      set:
        X-Api-Key: "${file:/run/secrets/backend_api_key}"

services:
  app:
    backends: [{ address: "10.0.0.5:3000" }]

Quote values that contain a reference. Inside YAML flow collections ({ … } and [ … ]), an unquoted } ends the value early.

With environment variables, for example to choose the backend per environment:

services:
  app:
    backends: [{ address: "${env:APP_BACKEND}" }]

Secret fields

Some fields are secrets. Their reference is not replaced when the configuration is loaded; it stays in the loaded configuration and is resolved only by the component that uses the value, at the moment it uses it:

certificates.<name>.key_password
acme.dns_providers.<name>.api_token (ACME is planned for v0.3)
acme.eab.hmac_key (ACME is planned for v0.3)

When a secret field holds a literal value instead of a reference, rdock validate warns:

warning: certificates.example.key_password: a secret is written in the configuration file
    store it as a file and reference it: "${file:/run/secrets/key_password}"

For every field, the configuration history and the last-known-good copy under $RDOCK_DATA_DIR/state store the document as you wrote it, with references unresolved. When a value from a reference fails to parse, the error message does not quote it.

Regular-expression replacements are literal

The replacement field of the redirect and rewrite middlewares is never interpolated, because $1 and ${name} there refer to capture groups of the regular expression:

middlewares:
  to-www:
    type: redirect
    regex: "^https://example\\.com/(.*)"
    replacement: "https://www.example.com/${1}"
    permanent: true

Secrets with Docker Compose

Compose mounts each secret as a file at /run/secrets/<secret_name> in the container (Docker documentation, checked 2026-10-27):

services:
  rdock:
    image: ghcr.io/docker-hunterpedia/rdock:0.3.0-alpha.1
    secrets: [example_key_password, backend_api_key]
    volumes:
      - ./config:/etc/rdock:ro
secrets:
  example_key_password:
    file: ./secrets/example_key_password.txt
  backend_api_key:
    file: ./secrets/backend_api_key.txt

Changing a secret

ReverseDock reloads on its own when rdock.yaml, certificate and key files, users_file of basic_auth and the page files of errors and maintenance change. Files read through ${file:…} are not watched. After changing a secret file or an environment value, reload:

rdock reload

A changed environment variable only reaches ReverseDock when the process is restarted, because the environment of a running process cannot be changed from outside. See Reload the configuration.

Validating in CI

rdock validate resolves references, so it needs the same variables and files as rdock run. In CI, provide placeholder values:

APP_BACKEND=app:3000 rdock validate --strict rdock.yaml