10 Most Used Docker Compose Files Explained

Introduction

In the world of containerization, Docker Compose is an indispensable tool for defining and running multi-container Docker applications. While Docker itself excels at managing single containers, most real-world applications consist of several interconnected services—a web application, a database, a cache, and perhaps an API gateway. Manually starting, linking, and managing each of these containers can quickly become cumbersome and error-prone. Docker Compose solves this problem by allowing you to define your entire application stack in a single, human-readable YAML file, which can then be brought up or down with a single command. This automation drastically simplifies the setup process.

The power of Docker Compose lies in its simplicity and declarative nature. Instead of writing complex shell scripts to orchestrate your containers, you describe the desired state of your application in a docker-compose.yml file. This includes defining services, networks, and volumes, along with their configurations and dependencies. This approach makes it incredibly easy to replicate development, testing, and even single-host production environments consistently across different machines. For developers, it means being able to spin up a full-fidelity local environment in seconds; for CI/CD pipelines, it ensures consistent testing environments; and for small-scale deployments, it provides a straightforward orchestration mechanism, significantly improving the entire development and deployment lifecycle.

This blog post will delve into 10 of the most commonly used Docker Compose file patterns and explain their purpose, structure, and best practices. We'll cover everything from basic web application setups and database integration to more advanced scenarios like defining custom networks, managing persistent data, and integrating with CI/CD workflows. Understanding these patterns is crucial for anyone working with Docker, as it unlocks the full potential of building and managing complex, containerized applications efficiently. By mastering these examples, you'll gain the confidence to structure your Docker Compose files effectively, streamlining your development and deployment workflows for greater productivity and consistency, ensuring the entire development lifecycle is integrated.

The Basics: version and services

Every Docker Compose file starts with a version key, which specifies the Compose file format version. This is important because different versions support different features. Following the version key, the services section is where you define all the individual containers that make up your application. Each entry under services represents a single service (e.g., a web app, a database, a Redis cache), and within each service, you specify its configuration. This includes the Docker image to use, port mappings, volume mounts, environment variables, and dependencies on other services. This declarative approach makes the entire application stack transparent and easy to manage, defining the blueprint for your multi-container application.

For example, a simple web application might have two services: web for the application server and db for the database. In the services section, you would define each of these with their respective Docker images (e.g., nginx, node, python, postgres), and any specific configurations they need. Docker Compose handles the networking between these services, allowing them to communicate with each other using their service names as hostnames. This eliminates the need for complex IP address management or manual docker run commands with --link flags, significantly simplifying the deployment and networking configuration of interdependent containers. The services section is the heart of your Docker Compose file, dictating how your application components will run and interact.

When choosing a version, it's generally best to use the latest stable version (e.g., 3.8 or higher) to leverage the most recent features and improvements. However, always consider compatibility with your Docker Engine version. The services definition allows for a wide range of parameters, making it incredibly flexible. This flexibility, coupled with the ability to define networks and volumes, is what makes Docker Compose so powerful for everything from simple development stacks to more complex microservices deployments. It provides a consistent way to manage all components of your application, ensuring that environments are reproducible and predictable, which is essential for both development and CI/CD pipelines. This consistency helps prevent the dreaded "it works on my machine" syndrome and allows for seamless handoffs, enhancing the overall velocity and efficiency of the team.

1. Basic Web Application with Database

This is arguably the most common Docker Compose pattern, used for setting up a typical web application stack. It usually involves a web server (like Nginx or Apache), an application server (e.g., Node.js, Python Flask/Django, Ruby on Rails), and a database (e.g., PostgreSQL, MySQL). This pattern demonstrates how to link these services, map ports, and use environment variables for configuration. This setup is perfect for local development or for deploying a small-scale application to a single server.

version: '3.8'
services:
  web:
    build: .
    ports:
      - "80:80"
    environment:
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
    depends_on:
      - db
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:
        

Explanation:

• web: Builds from a local Dockerfile (implicitly . means the current directory). Maps host port 80 to container port 80. Sets an environment variable DATABASE_URL for the web app to connect to the db service. depends_on ensures db starts before web.
• db: Uses the postgres:13 image. Sets environment variables for database credentials. Mounts a named volume db_data to /var/lib/postgresql/data for persistent database storage, ensuring data isn't lost when the container stops.
• volumes: Defines the named volume db_data.

This setup is robust for development, allowing developers to quickly spin up a full application stack. The use of named volumes ensures that database data persists across container restarts, providing a consistent development experience. Furthermore, the depends_on ensures services are started in the correct order, which is vital for database-dependent applications. This pattern is the starting point for nearly all multi-container applications, establishing a solid foundation for local testing and integration.

2. Development Environment with Hot Reloading

A common pain point for developers is the slow feedback loop when making code changes. Docker Compose can be configured to support hot reloading by mounting local source code into the container. This allows changes made on the host machine to be immediately reflected inside the container, without rebuilding the image or restarting the container. This pattern significantly speeds up the development process, making it a favorite for agile teams and greatly enhancing developer productivity. Achieving rapid iteration is key to minimizing context switching and ensuring continuous productivity throughout the coding process.

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./app:/app  # Mount local app directory to container
    environment:
      NODE_ENV: development
    command: npm run dev # Or specific command to start with hot-reloading
        

Explanation:

• app: Builds from a Dockerfile. Maps host port 3000 to container port 3000.
• volumes: - ./app:/app: This is the key for hot reloading. It mounts the local app directory (relative to docker-compose.yml) into the container's /app directory. Any changes to files in your local app directory will instantly appear inside the container.
• environment: NODE_ENV: development: Sets the development environment, which often triggers hot-reloading watchers within the application framework (e.g., Node.js or Python frameworks).
• command: npm run dev: Specifies the command to run when the container starts, often a script configured to watch for file changes and refresh the application automatically.

This pattern is invaluable for developers, streamlining the inner loop of coding, testing, and debugging. It ensures that the application behaves consistently within its containerized environment while allowing for rapid iteration, eliminating the need for constant manual rebuilds. It's a cornerstone for efficient local development workflows, proving that containerization doesn't have to sacrifice development speed. This capability is crucial for maximizing developer velocity and maintaining the rhythm of agile development sprints.

3. Reverse Proxy with Nginx

For applications with multiple services or for serving static files, using a reverse proxy like Nginx is a standard practice. This Docker Compose example shows how to set up Nginx to route traffic to your web application service, making it suitable for exposing multiple services on specific paths or domains. It also demonstrates mounting a custom Nginx configuration file, which is often necessary to correctly manage the routing and traffic flow to internal containers. This pattern is essential for centralized traffic management.

version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - web_app
  web_app:
    build: .
    expose:  # Exposes port 80 within the Docker network, not to the host
      - "80"
        

Explanation:

• nginx: Uses the official Nginx image. Maps host port 80 to container port 80.
• volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro: Mounts a local nginx.conf file to override the default Nginx configuration inside the container. :ro specifies read-only to prevent accidental modification at runtime.
• depends_on: - web_app: Ensures web_app starts before Nginx attempts to route traffic to it.
• web_app: Builds from a Dockerfile. expose: - "80" makes port 80 available to other services on the Docker network but does not publish it to the host machine. Nginx will communicate with web_app using its service name and exposed port, showing how API Gateways simplify deployment by acting as a single entry point.

This pattern is crucial for managing external access to your services, providing a single entry point, and enabling advanced routing rules. It also enhances security by not exposing every service directly to the internet. This setup demonstrates how to effectively manage multiple microservices behind a single entry point, a key pattern in microservices architecture, ensuring that client requests are properly directed to the appropriate backend service while enforcing traffic policies. The use of a proxy is a foundational technique in modern application scaling and security.

4. Microservices with Custom Networks

In a microservices environment, it's often beneficial to isolate services into their own networks for security and better organization. Docker Compose allows you to define custom networks, enabling fine-grained control over inter-service communication. This example illustrates how to create separate networks for different tiers of your application, enhancing security and manageability, which is a key pattern in advanced container networking and is crucial for maintaining security boundaries. Network segmentation limits the blast radius of any security breach or operational failure to the connected services.

version: '3.8'
services:
  webapp:
    build: ./webapp
    ports:
      - "8080:80"
    networks:
      - web-net
  api:
    build: ./api
    networks:
      - web-net
      - api-net
    depends_on:
      - db
  db:
    image: postgres:13
    networks:
      - api-net
    environment:
      POSTGRES_DB: api_db
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
networks:
  web-net:
  api-net:
        

Explanation:

• webapp: Only connected to web-net. It can communicate with other services on web-net but not directly with db on api-net, limiting its access.
• api: Connected to both web-net (to receive requests from webapp) and api-net (to connect to db). It acts as a bridge between the two networks.
• db: Only connected to api-net, ensuring it's not directly exposed to the webapp or other services on web-net. This isolation is a critical security measure.
• networks: Defines web-net and api-net as custom bridge networks, which are automatically managed by Docker Compose.

Custom networks are powerful for enforcing network segmentation and security boundaries between microservices. This pattern is particularly useful in larger applications where you want to control which services can communicate with each other, enhancing the overall security posture and reducing the attack surface. This is a foundational practice for robust multi-service deployments, especially within complex CI/CD pipelines that deploy many services simultaneously, ensuring that network policies are applied consistently from development through to production. This technique is indispensable for achieving high levels of security and compliance in distributed systems.

5. Multi-Stage Builds with a Dockerfile

While Docker Compose manages containers, the build instruction points to a Dockerfile that defines how an individual service's image is built. For efficient and secure images, multi-stage builds are a best practice. This pattern shows how to combine building and running stages within a single Dockerfile, resulting in smaller, more secure production images. This is essential for streamlining Continuous Delivery workflows by ensuring that images are optimized for deployment, reducing network transfer times, and minimizing the attack surface by excluding unnecessary build tools.

# Dockerfile (in ./app directory)
# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Run
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/build ./build
COPY package*.json ./
RUN npm install --omit=dev
CMD ["npm", "start"]
        

# docker-compose.yml
version: '3.8'
services:
  frontend:
    build: ./app # Points to the directory containing the Dockerfile
    ports:
      - "80:80"
        

Explanation:

• Dockerfile: The first stage (builder) builds the application, including dev dependencies. The second stage (FROM node:18-alpine) then copies only the necessary build artifacts from the builder stage, resulting in a lean final image without build tools or dev dependencies.
• frontend service: The build: ./app instruction in docker-compose.yml tells Compose to use the Dockerfile located in the ./app directory to build the frontend service's image.

Multi-stage builds are critical for creating efficient and secure Docker images. By separating build-time dependencies from runtime dependencies, you reduce the image size, decrease the attack surface, and speed up image pulls. This is a fundamental optimization for any production-ready containerized application, directly impacting deployment speed and security, which is a core tenet of modern DevOps practices. This technique is non-negotiable for anyone implementing serious application release automation and aiming for operational excellence, as it significantly reduces resource consumption and improves the overall security posture of the application.

6. Health Checks for Service Dependencies

While depends_on ensures services start in a specific order, it doesn't guarantee that a service is ready to accept connections. For instance, a database container might be started but still initializing. Health checks address this by periodically checking a service's readiness. If a service fails its health check, Docker Compose can be configured to not start dependent services or to restart the unhealthy service. This makes your application stack more robust and resilient, minimizing startup failures and improving overall system reliability, which is crucial for automated pipelines. It moves beyond simple process monitoring to true service readiness verification.

version: '3.8'
services:
  webapp:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:13
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
        

Explanation:

• db: Defines a healthcheck block.
  • test: The command to run to check health (pg_isready -U postgres checks PostgreSQL readiness). This must return a zero exit code for success.
  • interval: How often to run the check.
  • timeout: How long to wait for the command to return.
  • retries: How many times to retry before marking as unhealthy.
• webapp: depends_on: db: condition: service_healthy means webapp will only start once the db service passes its health check, preventing connectivity errors during startup.

Implementing health checks is a best practice for complex applications, especially those with critical dependencies like databases or message queues. It significantly improves the reliability and startup behavior of your application stack, preventing scenarios where a web app tries to connect to a database that isn't fully ready. This ensures smoother deployments and greater resilience in your development and testing environments, making it a critical component of robust application architecture. This is a foundational step in ensuring that your Continuous Delivery process is truly resilient against transient startup issues, contributing to a stable container orchestration environment.

7. Extending Configurations with extends

For large projects with many microservices, or when defining common configurations (e.g., logging, monitoring agents), you might find yourself repeating configuration blocks across multiple docker-compose.yml files. The extends keyword allows you to reuse configurations from another Compose file, promoting modularity and reducing duplication. This is particularly useful for managing environment-specific configurations (e.g., docker-compose.dev.yml vs. docker-compose.prod.yml) while ensuring that the core configurations remain consistent and centralized across the entire project structure.

# base.yml (common configuration)
version: '3.8'
services:
  app_base:
    image: myapp:latest
    environment:
      APP_VERSION: 1.0
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

# docker-compose.yml (extends base.yml for a specific service)
version: '3.8'
services:
  web:
    extends:
      file: base.yml
      service: app_base
    ports:
      - "80:80"
    environment:
      ENVIRONMENT: development
        

Explanation:

• base.yml: Defines a base service app_base with common configurations like image, a default environment variable, and logging settings. This file acts as a template for other configurations.
• docker-compose.yml: Defines a web service that extends the app_base service from base.yml. It inherits all configurations from app_base and then adds its own (e.g., ports, overrides environment).

The extends feature is invaluable for maintaining DRY (Don't Repeat Yourself) principles in your Docker Compose configurations. It simplifies the management of complex multi-service applications, especially when dealing with different environments or common infrastructure components. This modular approach makes your configurations more readable, maintainable, and less prone to errors, which is critical for long-term project health. This is a powerful feature for managing complex development workflows and ensuring consistency across various teams, reflecting principles often found in RHEL 10 post-installation checklist best practices by standardizing component setup.

8. Running One-Off Commands / CI/CD Integration

Docker Compose isn't just for long-running services; it's also excellent for executing one-off commands within the context of your application stack. This is particularly useful for database migrations, running tests, or performing administrative tasks. This capability makes it an ideal tool for integrating into CI/CD pipelines, where you might need to run tests or migrations against a temporary, isolated environment before deploying. It helps manage the entire container lifecycle from development to production by providing a consistent execution context for essential administrative tasks.

version: '3.8'
services:
  app:
    build: .
    environment:
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
    depends_on:
      - db
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:
        

Explanation of usage:

To run a database migration:

docker compose run app python manage.py migrate
        

To run tests:

docker compose run app npm test
        

• docker compose run: This command creates and runs a service container, executes a specified command, and then stops and removes the container.
• app: The name of the service (from docker-compose.yml) in which to run the command.
• python manage.py migrate or npm test: The command to execute within the app container.

This pattern makes Docker Compose incredibly versatile for CI/CD. You can spin up your entire application stack, run automated tests against it, execute database migrations, and then tear it all down, ensuring a clean and consistent environment for every build. This capability is fundamental to building robust, automated software delivery pipelines, ensuring that the DevOps continuous delivery pipeline always operates on a fresh, reliable environment. It provides consistency throughout the pipeline, which is essential for managing the release cadence in modern high-velocity environments, guaranteeing that every build is tested under near-production conditions.

9. Using Environment Variables for Configuration

Hardcoding sensitive information or environment-specific values directly into your docker-compose.yml or Dockerfile is a bad practice. Docker Compose allows you to use environment variables to externalize configurations, making your setups more flexible and secure. This is particularly useful for managing API keys, database credentials, or different build options across environments, adhering to the principles of twelve-factor apps. This separation of configuration from code is foundational for secure and portable containerized deployments.

version: '3.8'
services:
  web:
    build: .
    ports:
      - "${WEB_PORT:-80}:80" # Use WEB_PORT if set, otherwise default to 80
    environment:
      API_KEY: ${MY_API_KEY} # Reads from .env file or shell
      NODE_ENV: production
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: ${DB_NAME:-mydatabase}
      POSTGRES_USER: ${DB_USER:-user}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
        

Explanation:

• ${VARIABLE_NAME}: Docker Compose automatically reads environment variables from your shell environment or from a .env file located in the same directory as docker-compose.yml.
• ${VARIABLE_NAME:-default_value}: This syntax provides a default value if VARIABLE_NAME is not set. For example, WEB_PORT:-80 means use WEB_PORT if it exists, otherwise use 80.
• MY_API_KEY, DB_NAME, DB_USER, DB_PASSWORD: These would typically be defined in a .env file:

  
  # .env file
  WEB_PORT=8080
  MY_API_KEY=your_secret_api_key
  DB_PASSWORD=your_secure_password
                  

Externalizing configurations with environment variables is a fundamental security and flexibility best practice. It prevents sensitive data from being committed to version control and allows for easy adaptation of your Compose files to different deployment environments (development, staging, production) without modifying the YAML itself. This is particularly important for managing secrets securely and ensures that configuration is kept separate from code, which is a core tenet of building robust cloud-native applications and contributes to a robust GitOps approach. This technique is often coupled with other security measures like those found in RHEL 10 security enhancements for the underlying host.

10. Using profiles for Optional Services

In larger projects, you might have services that are only relevant in specific contexts (e.g., a debugging tool in development, a data analytics service in production, or specific database types for different microservices). Docker Compose profiles allow you to define optional services that are only started when explicitly activated. This keeps your docker-compose.yml cleaner and more manageable, as only relevant services are deployed for a given scenario. This is crucial for resource optimization and streamlining the development experience by only starting necessary components.

version: '3.8'
services:
  webapp:
    build: .
    ports:
      - "80:80"
  db:
    image: postgres:13
    volumes:
      - db_data:/var/lib/postgresql/data
  adminer:
    image: adminer
    ports:
      - "8080:8080"
    profiles: ["dev"] # Only starts if 'dev' profile is active
  redis:
    image: redis:6-alpine
    profiles: ["prod"] # Only starts if 'prod' profile is active
volumes:
  db_data:
        

Explanation:

• adminer: This database management tool service has profiles: ["dev"]. It will only be started when the dev profile is activated, making it an optional utility.
• redis: This caching service has profiles: ["prod"]. It will only be started when the prod profile is activated, ensuring the development environment is lightweight by default.

Usage:

# To start webapp, db, and adminer (for dev environment)
docker compose --profile dev up -d

# To start webapp, db, and redis (for production-like environment)
docker compose --profile prod up -d

# To start only webapp and db (default, no profile specified)
docker compose up -d
        

Profiles are extremely useful for managing complexity in large docker-compose.yml files. They allow teams to define a single Compose file that caters to multiple use cases (e.g., local development, testing, different production topologies), reducing the need for multiple, slightly different configuration files. This improves maintainability and ensures that only necessary services are consuming resources, optimizing both development and deployment environments. It's a key feature for managing a complex container orchestration landscape, enabling flexible and resource-efficient delivery, which adheres to the principles of efficient system management and helps in establishing strong log management best practices by limiting the scope of activated services.

Conclusion

Docker Compose is far more than just a tool for starting multiple containers; it's a powerful and flexible solution for defining, running, and managing complex multi-container applications throughout their lifecycle. By mastering the 10 patterns explained in this guide—from basic web application stacks and development environments with hot reloading to advanced microservices networking, health checks, and CI/CD integration—you unlock significant productivity gains and ensure consistency across your development, testing, and single-host deployment workflows. These patterns address common challenges and provide robust solutions for managing services, data persistence, network isolation, and configuration, proving its essential role in the modern container ecosystem.

The declarative nature of Docker Compose, coupled with its ability to manage networks, volumes, and environment variables, makes it an indispensable tool for any developer or DevOps engineer working with containers. It bridges the gap between individual container commands and full-fledged orchestration platforms like Kubernetes, providing an ideal solution for local development, testing, and small-to-medium scale deployments. By integrating these patterns into your daily workflow, you can streamline the setup of complex application stacks, improve collaboration within teams, and accelerate your software delivery cycles. This ensures that every developer can easily spin up a consistent environment, eliminating configuration drift and providing a reliable testing platform for all code changes.

As you continue your journey with Docker, remember that the docker-compose.yml file serves as the single source of truth for your application's architecture. Treat it with the same care as your application code, leveraging features like extends and profiles to keep it clean, modular, and maintainable. Embracing these best practices will not only enhance your personal productivity but also significantly contribute to the overall efficiency and reliability of your containerized projects, ensuring that your applications are always ready to be built, tested, and deployed with confidence and ease. The continuous evolution of Docker Compose ensures it remains a vital tool in the modern cloud-native ecosystem, providing a flexible way to manage your containerized applications, from small projects to complex, multi-service deployments, paving the way for advanced practices like those covered in which observability pillar is best for incident insight.

Frequently Asked Questions

What is Docker Compose used for?

Docker Compose is used to define and run multi-container Docker applications by defining all services, networks, and volumes in a single YAML file.

What is the purpose of the version key in a Docker Compose file?

The version key specifies the Compose file format version, which dictates the features and syntax supported by the Docker Engine.

How do services in Docker Compose communicate with each other?

Services communicate using their service names as hostnames within the Docker network automatically created by the Compose environment.

What is "hot reloading" in the context of Docker Compose development?

Hot reloading allows local code changes on the host machine to be instantly reflected inside a running container, achieved by mounting local source code as a volume.

Why would you use a reverse proxy like Nginx with Docker Compose?

A reverse proxy is used to route external traffic to different internal services, provide a single entry point, serve static files, and enhance application security.

What are the benefits of using custom networks in Docker Compose?

Custom networks enable network segmentation, isolating services for security and better organization, and controlling inter-service communication explicitly.

What are "multi-stage builds" in a Dockerfile, and why are they important?

Multi-stage builds use multiple FROM instructions to create smaller, more secure Docker images by separating build-time dependencies from runtime dependencies.

How do health checks improve Docker Compose deployments?

Health checks ensure that services are not just started but are fully ready and healthy before dependent services attempt to connect, improving startup reliability.

When should I use the extends keyword in Docker Compose?

Use extends to reuse common configurations from a base Docker Compose file across multiple specific Compose files, promoting modularity and consistency.

How can Docker Compose be integrated into a CI/CD pipeline?

By using docker compose up to spin up a testing environment and docker compose run to execute one-off commands like tests or database migrations against that environment.

What is the purpose of .env files with Docker Compose?

.env files store environment variables (e.g., database credentials, API keys) that are read by Docker Compose, externalizing configuration for flexibility and security.

What are Docker Compose profiles used for?

Profiles allow you to define optional services that are only started when explicitly activated, enabling a single docker-compose.yml file to serve multiple use cases.

What is the difference between ports and expose in Docker Compose?

ports publishes container ports to the host machine, making them accessible externally. expose makes ports accessible to other services within the Docker network only.

How does Docker Compose help with local microservices development?

It allows developers to spin up an entire microservices architecture locally with a single command, ensuring consistency with production environments and simplifying local testing and debugging.

How does Docker Compose relate to advanced release cadence management?

It provides rapid, repeatable environments for testing, ensuring reliable builds that can be released quickly, supporting the high-frequency requirements of fast-paced DevOps teams.