Configuration

Most people know docker compose config as “the validate command”. It’s much more than that. The same command can list resources, output JSON, hash services for change detection, and pin image digests for reproducibility. Listing resources Ask Compose what’s actually in your project, after all overrides and interpolation: # List all services docker compose config --services # List all volumes docker compose config --volumes # List all images used docker compose config --images # List all defined profiles docker compose config --profiles These are great in scripts when you need to loop over each service: ...

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: ...