How to Create a Docker Compose File (Production Ready)

A docker-compose.yml file is the blueprint for a multi-container Docker application. While anyone can throw together a basic Compose file that runs locally, structuring one for reliability, security, and production readiness requires a deeper understanding of Docker's networking, volume management, and lifecycle hooks.

1. Start with the Version and Basic Structure

At the root of every Compose file, you define the services, networks, and volumes. While the version tag is technically optional in newer Compose V2 specs, it's still widely used for backwards compatibility.

version: "3.8"
services:
  # Your containers go here
volumes:
  # Persistent data mounts go here
networks:
  # Custom networks go here

2. Define Your Services (API & Database)

Let's define a Node.js API and a PostgreSQL database. Notice how we use environment variable interpolation (${POSTGRES_PASSWORD}) rather than hardcoding credentials directly into the file.

services:
  api:
    image: my-node-api:1.0.0
    ports:
      - "3000:3000"
    environment:
      - DB_HOST=db
      - DB_USER=postgres
      - DB_PASSWORD=${POSTGRES_PASSWORD}
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

3. The Critical Missing Piece: Healthchecks

In the example above, the api service waits for the db service using condition: service_healthy. However, this will fail unless the database actually defines what "healthy" means. Without a healthcheck, Docker assumes a container is ready the millisecond the process starts, causing your API to crash when it tries to connect to a database that is still initializing.

  db:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

4. Resource Limits (Preventing Crashes)

By default, a Docker container can consume all the CPU and Memory of the host machine. If your Node.js app has a memory leak, it can take down the database and the entire server. You must set limits.

  api:
    image: my-node-api:1.0.0
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
        reservations:
          cpus: "0.1"
          memory: 128M

Summary of Best Practices

• Never hardcode secrets: Use .env files and variable interpolation.
• Always define healthchecks: Ensure dependencies are fully initialized before linking services.
• Always mount volumes for databases: Containers are ephemeral. If you don't mount a volume, your database will wipe clean when the container restarts.
• Set resource limits: Prevent noisy-neighbor problems on a shared host.
• Use explicit tags: Avoid latest (e.g., use postgres:15-alpine instead of postgres).