Docker & Docker Compose Best Practices Guide

Choose the Right Base Image

Select minimal, trusted base images:

• Use Docker Official Images or Verified Publisher images when possible.
• Consider Alpine-based images (e.g., node:18-alpine) for significantly smaller footprints, but be aware of potential compatibility differences (musl vs glibc).
• Pin specific versions (e.g., ubuntu:22.04, node:18.17.1-alpine) instead of using floating tags like latest or alpine to ensure reproducibility and avoid unexpected breaking changes.

This reduces image size, attack surface, and ensures consistent builds. [Reference]

Multi-stage Builds for Smaller Images

Multi-stage builds dramatically reduce your final image size by separating build-time dependencies from runtime needs. Only copy necessary artifacts to the final stage.

FROM node:18 AS builder # Build stage
WORKDIR /app
COPY package*.json ./
RUN npm install # Install all deps, including devDeps
COPY . .
RUN npm run build # Create build artifacts in /app/dist

FROM node:18-alpine AS production # Final stage
WORKDIR /app
# Copy only build artifacts and necessary package files from builder stage
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm install --production # Install only runtime deps
USER node
CMD ["node", "dist/server.js"]

This creates smaller, more secure production images. [Reference]

Use BuildKit Cache Mounts (for Dependencies)

Leverage BuildKit cache mounts to speed up dependency installation during builds without bloating image layers. Enable BuildKit (often default in newer Docker versions, or use `DOCKER_BUILDKIT=1`).

# Example for npm
RUN --mount=type=cache,target=/root/.npm npm install

# Example for apt
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y ...

# Example for pip
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

This caches package manager data between builds, significantly speeding up installs if dependency files haven't changed.

Don't Install Unnecessary Packages

Only install packages absolutely required for your application to run. Combine installation and cleanup in a single RUN command to minimize layer size.

RUN apt-get update && apt-get install -y --no-install-recommends \
    package1 package2 \
    && rm -rf /var/lib/apt/lists/* # Clean up apt cache

This reduces image size, potential vulnerabilities, and build time. [Reference]

Follow Instruction Best Practices

• Use proper FROM instructions with specific versions (see Base Image).
• Order instructions logically to maximize cache usage (install dependencies before copying frequently changing code).
• Combine related RUN commands using && and backslashes (\) for readability, and clean up temporary files within the same layer.
• Use WORKDIR to set context instead of chaining cd in RUN commands. Use absolute paths for clarity (e.g., WORKDIR /app).
• Use COPY over ADD unless you specifically need ADD's auto-extraction or URL features.
• Add meaningful LABEL metadata (maintainer, description, version).
• Use a non-root USER for security.
• Define HEALTHCHECK, EXPOSE, VOLUME as appropriate.
• Understand the difference between ENTRYPOINT and CMD.

[Dockerfile Best Practices]

Review Language-Specific Examples

Docker provides guides and examples tailored to specific programming languages and frameworks. Reviewing these can help you adopt conventional practices for your stack.

[Language-Specific Guides]

Decouple Applications into Separate Containers

Each container should ideally have a single responsibility (e.g., web server, database, cache, message queue). This promotes the "one process per container" principle.

• Split your web application, database, and cache into separate services in your compose.yaml.
• Use Docker networks (Compose creates a default one, or you can define custom networks) to enable communication between these services. Services can reach each other using their service name as the hostname (e.g., `db` from the `app` service).

This makes scaling, maintenance, and reuse easier. [Reference]

Understand the Compose Application Model

Be familiar with the core concepts defined in a Compose file:

• Services: Define the containers that make up your application.
• Networks: Define how containers connect and communicate.
• Volumes: Define persistent data storage.
• Configs & Secrets: Define ways to securely provide configuration and sensitive data.

[How Compose works]

Use Compose for Development Consistency

Docker Compose is excellent for creating reproducible development environments.

• Define all required services (app, db, cache, etc.) in compose.yaml.
• Use volumes to mount your source code into the container for live updates (e.g., volumes: - ./src:/app/src).
• Control startup order using depends_on with condition: service_healthy, ensuring dependencies are ready.

services:
  web:
    build: .
    ports:
      - "8080:80"
    volumes:
      - ./src:/app/src # Mount source code
    depends_on:
      db:
        condition: service_healthy # Wait for db healthcheck
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    # ... other db config

[Common Questions]

Optimize Service Definitions

Review the configuration for each service in your Compose file:

• Set appropriate restart policies (e.g., restart: unless-stopped for production services).
• Define meaningful health checks (healthcheck) so Docker knows if your service is running correctly.
• Use environment variables (environment: or env_file:) for configuration, but prefer secrets for sensitive data.
• Consider setting resource limits (deploy: resources: limits: ...) in production environments, especially when using Swarm or Kubernetes.

[Compose in Production]

Use Secrets for Sensitive Data

Avoid hardcoding passwords, API keys, or other sensitive information directly in your Compose file or environment variables. Use Docker secrets instead.

services:
  app:
    image: my-app
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password # App reads from this file
    secrets:
      - db_password # Grant access to the secret

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password # Postgres reads from this file
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt # Source the secret from this host file

Secrets are mounted as files into /run/secrets/ within the container, preventing exposure in logs or via docker inspect.

[Secrets in Compose]

Leverage Service Extension (extends)

Use the extends attribute to share common configurations between services or across multiple Compose files, promoting the DRY (Don't Repeat Yourself) principle.

# common-services.yaml
services:
  base-app:
    restart: unless-stopped
    networks:
      - backend

# compose.yaml
services:
  web:
    extends:
      file: common-services.yaml
      service: base-app
    build: ./web
    ports: ["80:80"]

  api:
    extends:
      file: common-services.yaml
      service: base-app
    build: ./api

[Extend Service]

Optimize for Different Environments

Use multiple Compose files to manage configurations for different environments (e.g., development, testing, production).

• Create a base compose.yaml with common configurations.
• Create override files like compose.dev.yaml, compose.prod.yaml.
• Use the -f flag to specify which files to merge:
  docker compose -f compose.yaml -f compose.prod.yaml up
• Alternatively, use profiles (see Project Structure section) to enable/disable services based on environment.

[Multiple Compose Files]

Study Sample Applications

Explore the Awesome Compose repository for examples of how to structure Compose projects for various technology stacks.