Environment Variables in Docker Compose

Why it exists

To decouple an application's configuration from its code. Hardcoding values like database hosts or API keys into a container image makes it inflexible and insecure. Environment variables allow the same image to be used across different stages (development, staging, production) simply by changing its runtime configuration.

The mental model

Think of your docker-compose.yml as a blueprint for a multi-service application. The environment section for each service is a set of instructions you pass to it at startup. It's like telling your web server container, 'Here is the address for the database,' without having to write that address into the server's source code.

How it works

Docker Compose provides several ways to set environment variables for a container, which are applied in a specific order of precedence. You can set them directly in the docker-compose.yml using the environment key as a list or a map. You can also use an env_file key to point to a file with variable definitions. Additionally, a file named .env in your project directory can be used to set default values for variables used within the Compose file itself. Finally, variables exported in your shell will override values in the .env file. Understanding this precedence is key to avoiding configuration conflicts.

When to use it

Use environment variables for any configuration that changes between deployments or environments. This includes database connection strings, external API endpoints, credentials for development, log level settings, and feature flags.

When not to use it

Avoid storing sensitive production secrets (like production database passwords or private API keys) directly in docker-compose.yml or .env files, especially if they are committed to version control. For production, use a dedicated secrets management tool like Docker Secrets, HashiCorp Vault, or a cloud provider's secret manager.

One canonical example

A web application service needs to connect to a database service. The docker-compose.yml defines both and uses environment variables to pass the database credentials to the web app.

services: db: image: postgres:14 environment: - POSTGRES_USER=myuser - POSTGRES_PASSWORD=mypassword web: build: . ports: ["8000:8000"] environment: - DB_HOST=db - DB_USER=myuser - DB_PASSWORD=mypassword

Here, the web service can use the DB_HOST, DB_USER, and DB_PASSWORD variables to construct its connection string.