Environment & Interpolation

## Two moments, two consumers Docker Compose touches variables at two separate points, and most confusion about `.env` comes from mixing them up: - **Interpolation** happens while Compose *parses* `compose.yaml`. Every `${VAR}` or `$VAR` placeholder in a YAML value is replaced with text before Compose builds its model of the project. The consumer is the **compose file**. - **Container environment** is applied when Compose *creates* a service's container. The consumer is the **process inside the container**. The project `.env` file belongs to the first moment. The `environment` and `env_file` attributes belong to the second. ## The project `.env` file: input to interpolation When you run `docker compose up` without `--env-file`, Compose looks for a file named `.env` in the **project directory** (by default the directory of the first compose file) and loads its `KEY=value` lines into the *interpolation environment*, next to the variables already exported in your shell. - It is read by Compose itself, not by any container. - It controls text such as `image: "api:${APP_TAG}"` or `ports: ["${API_PORT}:8080"]`. - It can also carry Compose's own `COMPOSE_*` settings. - A key in `.env` that nothing in `compose.yaml` refers to, by placeholder or by a bare pass-through key, has no effect unless it is one of Compose's own `COMPOSE_*` settings. ## `environment` and `env_file`: input to the container These are **service attributes** in `compose.yaml`: - `environment` lists variables inline, as a map (`LOG_LEVEL: info`) or a list (`- LOG_LEVEL=info`). - `env_file` names one or more files whose lines are loaded into that service's container. Relative paths are resolved from the compose file's directory, and later files in the list override earlier ones. - When both set the same key, **`environment` wins**. | Mechanism | Read by | When | Reaches the container? | |---|---|---|---| | project `.env` | Compose | while parsing `compose.yaml` | only through a placeholder in `environment` or `env_file` | | `env_file:` | Compose, for one service | when the container is created | yes, every key in the file | | `environment:` | Compose, for one service | when the container is created | yes, every listed key | ## One syntax, two readers The project `.env` and the files named in `env_file` share one line format, and Compose parses both itself — no shell is involved: - One `KEY=value` pair per line; lines starting with `#` and blank lines are ignored. - An optional leading `export ` is accepted, so the same file can also be sourced by a shell script. - Unquoted and double-quoted values are **interpolated**, so a value may reference another variable; single-quoted values are taken **literally**. - An inline comment after an unquoted value needs a space before the `#`; `VAL# text` keeps the `#` as part of the value. Sharing the syntax is what makes the two easy to confuse. The file format says nothing about *who reads the file*: the same lines placed in `.env` shape the compose file, and placed in a file listed under `env_file` they become container variables. ## Passing a `.env` value into a container To get a value from `.env` into the process, reference it from a container-facing attribute: ```yaml services: api: image: "api:${APP_TAG:-dev}" environment: DB_PASSWORD: ${DB_PASSWORD} env_file: - ./api.env ``` Here `APP_TAG` and `DB_PASSWORD` are interpolated from the shell or `.env`; `DB_PASSWORD` then reaches the container because `environment` names it, while `APP_TAG` only shapes the image reference. Everything in `api.env` reaches the container directly. A shorter pass-through form is a bare key, `- DB_PASSWORD`, which takes the value from Compose's environment without the placeholder. ## Laptop-to-CI traps The split explains the classic "works on my machine" failures when the same stack moves to a CI job: 1. **`.env` is gitignored.** The runner has no `.env`, so `${DB_PASSWORD}` resolves to nothing. Compose prints a warning such as `The "DB_PASSWORD" variable is not set. Defaulting to a blank string.` and starts the database with an empty password rather than failing. 2. **`env_file` names a missing file.** Each `env_file` entry is required by default, so a missing file stops Compose with an `env file ... not found` error. Since Compose 2.24 the long syntax `- path: ./api.env` with `required: false` makes the entry optional. 3. **One file, two roles.** Pointing `env_file` at `.env` is legal: the same file then feeds interpolation *and* is copied into the container, which can leak every key, including ones meant only for Compose. ## Checking it `docker compose config` prints the model after interpolation, with each service's `env_file` contents folded into its `environment`. It is the quickest way to see what a container will actually receive.