Docker Compose Secrets

Docker Compose has a native secrets mechanism that mounts sensitive values as files inside the container at /run/secrets/, rather than exposing them as environment variables. This is a Docker-level feature — it is independent of Distr Secrets and can be used on its own or in combination with them.

When to use Docker Compose Secrets

Approach	How the secret reaches the container	Use when
Env var (standard)	ENV_VAR=value in the environment	The application reads from os.environ
Docker Compose Secrets	File at /run/secrets/filename	The application expects a file path, or you want to avoid secrets appearing in docker inspect output

Both approaches can pull the underlying secret value from Distr Secrets. The difference is the delivery mechanism, not the source.

How Docker Compose Secrets work

The secrets section in your compose.yaml defines a named secret and where its value comes from. Services that need it declare it under their secrets key, and Docker mounts it as a read-only file inside the container.

services:
  backend:
    image: my-application-backend
    secrets:
      - api-key.txt
    environment:
      # Tell the app where to find the secret file
      API_KEY_PATH: /run/secrets/api-key.txt

secrets:
  api-key.txt:
    environment: API_KEY # Reads from the API_KEY environment variable

The environment: API_KEY line tells Docker Compose to populate the secret from the API_KEY environment variable, which it reads from the .env file passed by the Distr agent.

Using Docker Compose Secrets without Distr Secrets

You can hardcode the value directly in the .env file:

API_KEY="my-actual-secret-value"

This works but stores the raw value in your deployment configuration. Anyone with access to the deployment in Distr can see it.

Combining with Distr Secrets

The recommended approach is to use Distr Secrets to store the value and inject it into the .env file via template syntax. The Distr agent substitutes the template before passing the file to Docker Compose:

API_KEY="{{ .Secrets.API_KEY }}"

Note

Docker’s .env file syntax does not support multi-line values. If your secret contains newline characters, Distr escapes them automatically to \n. Docker Compose only interprets these escape sequences in double-quoted values, so always wrap your secret references in double quotes as shown above.

The full flow is:

1. Distr replaces {{ .Secrets.API_KEY }} with the actual value from the secret store
2. The Distr agent passes the resolved .env file to Docker Compose
3. Docker Compose reads API_KEY from the .env and creates the secret
4. The secret is mounted as /run/secrets/api-key.txt inside the container
5. Your application reads the file at the path from API_KEY_PATH

Related

• Secrets Management — store and template-reference secret values in Distr
• Docker Environment Variables — configure environment variables for Docker deployments