Docker & Compose¶

dotenv-fusion can pass resolved values directly to Docker, generate a dotenv file for Compose, or create a file consumed through Compose secrets:. Choose the path that matches how the container expects configuration.

Docker run: pass environment variables¶

Resolve the configuration in the Docker CLI process, then forward selected variables into the container:

dotenv-fusion exec -f .env-fuse -- \
  docker run --rm \
    --env DB_USERNAME \
    --env DB_PASSWORD \
    my-application:latest

Docker reads each named value from the environment prepared by exec. Values do not appear in the command line, though they remain environment variables inside the container.

Users with Docker administration access can inspect a container's resolved environment. Commands such as docker compose config can also print interpolated values; dotenv-fusion cannot redact output produced by Docker.

Docker run: generate an env file¶

docker run --env-file uses a raw line format. Generate the Docker dialect:

dotenv-fusion fuse --dialect docker -o .env.docker
docker run --rm --env-file .env.docker my-application:latest

The generated file contains plaintext values. Keep it out of Git, restrict its permissions, and remove it when the consumer no longer needs it.

Compose: pass environment variables¶

Compose can inherit values from the environment running the CLI:

compose.yml

services:
  application:
    image: my-application:latest
    environment:
      DB_PASSWORD:

dotenv-fusion exec -f .env-fuse -- docker compose up -d

An empty mapping value tells Compose to read DB_PASSWORD from its parent environment.

Compose: generate a project `.env`¶

Compose understands the default dotenv dialect:

dotenv-fusion fuse -f .env-fuse -o .env
docker compose up -d

This is useful when Compose interpolation needs the values. The .env file is a plaintext artifact and should normally be ignored by Git.

Compose: provide a secret file¶

When the image supports a _FILE variable, let Compose expose a resolved environment value as a file inside the container:

compose.yml

services:
  application:
    image: my-application:latest
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    environment: DB_PASSWORD

Launch Compose through dotenv-fusion:

dotenv-fusion exec -f .env-fuse -- docker compose up -d

The service receives /run/secrets/db_password instead of a DB_PASSWORD environment variable. DB_PASSWORD_FILE is an application convention; use the file setting supported by the selected image. Compose environment: secret sources are not supported by docker stack deploy.

Compose handles plaintext delivery to the container. The application and Docker administrators can still access the delivered value, and dotenv-fusion cannot redact output produced by Docker or the application.

Compose secrets: can also be used with a plaintext source file or an externally supplied environment variable. dotenv-fusion adds encrypted age bundles, explicit selectors, and configuration validation before Compose delivery; it does not change Docker's runtime access model.

For age-backed values, configure the source first in Get Started with age. The storage and exposure tradeoffs are documented in Security & Limitations.