Configuration

Every Compose stack gets a project name. It prefixes all resource names such as containers, networks, volumes. Understanding how it works avoids naming conflicts and makes multi-environment setups cleaner. Default behavior By default, the project name is the directory name where your compose.yml lives: my-app/ compose.yml docker compose up -d # Creates: my-app-web-1, my-app-db-1, my-app_default network Setting the project name Three ways to set it, in order of precedence: # 1. CLI flag (highest precedence) docker compose -p myproject up # 2. Environment variable COMPOSE_PROJECT_NAME=myproject docker compose up # 3. In the Compose file itself # compose.yml name: myproject services: web: image: nginx The name key in the Compose file is the recommended approach, it’s versioned with your code and everyone on the team gets the same project name. ...

Build args and environment variables both pass values to your containers, but they work at different times and serve different purposes. Mixing them up is a common source of confusion. Build args: build-time only Build args are available during docker build and are not present in the running container: services: app: build: context: . args: NODE_VERSION: "20" APP_VERSION: "2.1.0" In the Dockerfile, they’re consumed with ARG: ...

Docker Compose supports shell-style variable substitution in your Compose files. Combined with defaults and error messages, it makes your configurations flexible and safe. Basic substitution Reference environment variables or .env file values: services: app: image: myapp:${TAG} environment: DATABASE_URL: postgres://${DB_USER}:${DB_PASS}@db/${DB_NAME} # .env TAG=2.1.0 DB_USER=admin DB_PASS=secret DB_NAME=myapp Default values Provide fallback values when a variable is unset or empty: services: app: image: myapp:${TAG:-latest} environment: LOG_LEVEL: ${LOG_LEVEL:-info} PORT: ${PORT:-3000} deploy: replicas: ${REPLICAS:-1} Two syntaxes with a subtle difference: ...

Labels are key-value metadata attached to containers. They cost nothing at runtime but unlock powerful filtering, organization, and tool integrations. Adding labels to services services: api: image: myapp-api labels: com.example.team: "backend" com.example.env: "production" com.example.version: "2.1.0" worker: image: myapp-worker labels: com.example.team: "backend" com.example.env: "production" com.example.role: "async-processing" You can also use the list syntax: services: api: image: myapp-api labels: - "com.example.team=backend" - "com.example.env=production" Filtering with labels Labels become powerful with docker compose ps: ...

The real power comes from using all three mechanisms together, each doing what it does best. The scenario A team maintaining a web application with: Shared infrastructure (database, monitoring) reused across projects Common service configuration (logging, labels) applied to all services Different settings for local development vs CI vs production Project structure my-project/ ├── compose.yml # Main entry point ├── compose.override.yml # Local dev overrides ├── compose.ci.yml # CI-specific overrides ├── base/ │ └── service-base.yml # Shared service config (extends) └── infra/ ├── database.yml # Postgres stack (include) └── monitoring.yml # Prometheus + Grafana (include) Step 1: Shared service config with extends Define common configuration once: ...