docker-patterns

name	docker-patterns
description	Docker and Docker Compose patterns for local development, container security, networking, volume strategies, and multi-service orchestration. Use when authoring or debugging a Dockerfile / compose file, bringing the local DevSkyy stack up, or diagnosing container networking, healthcheck, or volume failures. Do NOT use for production orchestration on Fly/Vercel/Kubernetes, for WordPress theme deploys (that is wp-deploy — skyyrose.co is WP.com Atomic, not containerized), or for schema changes inside the DB container (that is database-migrations).
origin	ECC

Docker Patterns

Docker and Docker Compose best practices for containerized development.

When to use

• Setting up Docker Compose for local development
• Designing multi-container architectures
• Troubleshooting container networking, healthchecks, or volume issues
• Reviewing Dockerfiles for security and size
• Migrating from local dev to containerized workflow

When NOT to use:

• skyyrose.co — WP.com Atomic hosting, no containers involved. Theme changes go through wp-deploy.
• Production orchestration (Fly.io for api.devskyy.app, Vercel for devskyy.app) — Compose is a local-dev tool here; docker-compose.prod.yml patterns below are reference, not this repo's production path.
• Schema/data changes inside devskyy-postgres → database-migrations (Alembic is canonical).
• Cache key design or eviction inside devskyy-redis → redis-patterns.

Inputs

Absent input = STOP. A compose stack started with guessed secrets is worse than one that refuses to start — it silently gets a different DB than every other developer.

1. .env.docker with real values. docker-compose.yml interpolates POSTGRES_PASSWORD, REDIS_PASSWORD, and friends into the shared x-app-env anchor. Absent → docker compose refuses to even parse the file (see Worked example — this is the correct fail-closed behavior). Generate it with make docker-secrets, then paste API keys in. Never invent a password to get past the error.
2. A running Docker daemon. docker info must succeed. A dead daemon makes every subsequent command fail in ways that look like config bugs.
3. The repo root as the compose working directory — docker-compose.yml, Dockerfile, and .env.docker all resolve relative to it. Never use repo-relative paths from a random cwd (bug-288: cwd persists silently between calls; use absolute paths).
4. Free host ports for anything you publish (APP_PORT defaults to 8000). A port already bound by another stack surfaces as a container that starts then dies.

Procedure

1. make docker-secrets if .env.docker does not exist; fill in API keys.
2. Validate the compose file before starting anything: docker compose config --services (Verification check 1). A parse/interpolation error here is a stop, not a warning.
3. make docker-up (build + start the core stack: app, postgres, redis, workers).
4. Wait for healthchecks, then confirm every service reports (healthy) — not merely Up (Verification check 2). depends_on: condition: service_healthy means an unhealthy postgres silently holds the app in "Created".
5. Probe the app's own health endpoint through the published port (Verification check 3).
6. On failure, read logs for the specific service (docker compose logs --tail=50 <svc>) before changing config — most "networking" bugs are a service that never became healthy.
7. Tear down with docker compose down. docker compose down -v destroys the named volumes (postgres_data, redis_data) — that is irreversible data loss and a STOP-AND-SHOW action.

Verification

Every check below can return "no". A command that errored or timed out is an artifact, not a pass — re-run it (bug-230). docker compose ps showing Up is not the same as (healthy); treating "started" as "working" is the fail-open shape this stack is most prone to.

cd /Users/theceo/DevSkyy && docker compose config --services

PASS: exits 0 and lists the expected services. Any interpolation error means a required secret is missing — fix .env.docker, never hand-edit the compose file to dodge it. [repro]

docker compose ps --format '{{.Name}} {{.Status}}'

PASS: every core service line contains (healthy). Observed 2026-07-28: devskyy-app, devskyy-postgres, devskyy-redis, devskyy-worker, devskyy-elite-worker all Up 35 hours (healthy) [repro]. A service stuck at Up (health: starting) past its start_period (40s for app) is failing, not booting.

docker exec devskyy-postgres sh -c 'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"' && \
docker exec devskyy-redis  sh -c 'REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli ping'

PASS: accepting connections and PONG. Observed 2026-07-28: PONG [repro]. These mirror the healthchecks at docker-compose.yml:73 (pg_isready -U devskyy -d devskyy) and :94 (redis-cli -a "$$REDIS_PASSWORD" ping | grep -q PONG), but pass credentials via env (REDISCLI_AUTH) instead of argv; running them by hand is how you distinguish "healthcheck is wrong" from "service is down". A bare redis-cli ping returning NOAUTH Authentication required. is the password being enforced, not an outage. [repro]

curl -fsS "http://localhost:${APP_PORT:-8000}/health"

PASS: exits 0 with a JSON health body — the same probe as the app healthcheck (docker-compose.yml:127), but from the host, which additionally proves the port publish works. [repro]

Prove the checks can fail (rule 3): docker compose stop redis, re-run check 2 — the app must go unhealthy — then docker compose start redis. A health gate never observed going red is a guess with a citation.

Docker Compose for Local Development

Standard Web App Stack

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # Use dev stage of multi-stage Dockerfile
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # Bind mount for hot reload
      - /app/node_modules             # Anonymous volume -- preserves container deps
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_dev
    volumes:
       
       
    
       [, ]
       
       
       

  
     
    
       
    
       

                              
     
    
                          
                          


  
  

Development vs Production Dockerfile

# Stage: dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Stage: dev (hot reload, debug tools)
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]

# Stage: build
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production

# Stage: production (minimal image)
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

Override Files

# docker-compose.override.yml (auto-loaded, dev-only settings)
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    ports:
      - "9229:9229"                   # Node.js debugger

# docker-compose.prod.yml (explicit for production)
services:
  app:
    build:
      target: production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

# Development (auto-loads override)
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Networking

Service Discovery

Services in the same Compose network resolve by service name:

# From "app" container:
postgres://postgres:postgres@db:5432/app_dev    # "db" resolves to the db container
redis://redis:6379/0                             # "redis" resolves to the redis container

Custom Networks

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net              # Only reachable from api, not frontend

networks:
  frontend-net:
  backend-net:

Exposing Only What's Needed

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"   # Only accessible from host, not network
    # Omit ports entirely in production -- accessible only within Docker network

Volume Strategies

volumes:
  # Named volume: persists across container restarts, managed by Docker
  pgdata:

  # Bind mount: maps host directory into container (for development)
  # - ./src:/app/src

  # Anonymous volume: preserves container-generated content from bind mount override
  # - /app/node_modules

Common Patterns

services:
  app:
    volumes:
      - .:/app                   # Source code (bind mount for hot reload)
      - /app/node_modules        # Protect container's node_modules from host
      - /app/.next               # Protect build cache

  db:
    volumes:
      - pgdata:/var/lib/postgresql/data          # Persistent data
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # Init scripts

Container Security

Dockerfile Hardening

# 1. Use specific tags (never :latest)
FROM node:22.12-alpine3.20

# 2. Run as non-root
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app

# 3. Drop capabilities (in compose)
# 4. Read-only root filesystem where possible
# 5. No secrets in image layers

Compose Security

services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /app/.cache
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE          # Only if binding to ports < 1024

Secret Management

# GOOD: Use environment variables (injected at runtime)
services:
  app:
    env_file:
      - .env                     # Never commit .env to git
    environment:
      - API_KEY                  # Inherits from host environment

# GOOD: Docker secrets (Swarm mode)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# BAD: Hardcoded in image
# ENV API_KEY=sk-proj-xxxxx      # NEVER DO THIS

.dockerignore

node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/

Debugging

Common Commands

# View logs
docker compose logs -f app           # Follow app logs
docker compose logs --tail=50 db     # Last 50 lines from db

# Execute commands in running container
docker compose exec app sh           # Shell into app
docker compose exec db psql -U postgres  # Connect to postgres

# Inspect
docker compose ps                     # Running services
docker compose top                    # Processes in each container
docker stats                          # Resource usage

# Rebuild
docker compose up --build             # Rebuild images
docker compose build --no-cache app   # Force full rebuild

# Clean up
docker compose down                   # Stop and remove containers
docker compose down -v                # Also remove volumes (DESTRUCTIVE)
docker system prune                   # Remove unused images/containers

Debugging Network Issues

# Check DNS resolution inside container
docker compose exec app nslookup db

# Check connectivity
docker compose exec app wget -qO- http://api:3000/health

# Inspect network
docker network ls
docker network inspect <project>_default

Worked example

Real invocation in this repo, 2026-07-28 — the fail-closed path first:

cd /Users/theceo/DevSkyy/.claude/worktrees/glimmering-crafting-shannon
docker compose config --services; echo "exit=$?"
docker info >/dev/null 2>&1 && echo "daemon=UP" || echo "daemon=DOWN"

Observed [repro]:

error while interpolating x-app-env.DATABASE_URL: required variable POSTGRES_PASSWORD is missing a value: set POSTGRES_PASSWORD in .env.docker
exit=1
daemon=UP

That is the gate working exactly as it should: the daemon is fine, but .env.docker is absent in this worktree, so Compose refuses to produce a config at all rather than interpolating an empty password into DATABASE_URL and quietly connecting to a different database. The fix is make docker-secrets — never "just export POSTGRES_PASSWORD=postgres to get past it".

The already-running stack (started from the main checkout, which has .env.docker):

docker ps --format '{{.Names}} {{.Status}}'
docker exec devskyy-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "SELECT current_database(), version();"'
docker exec devskyy-redis sh -c 'REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli ping'

Observed [repro]:

devskyy-elite-worker Up 35 hours (healthy)
devskyy-worker       Up 35 hours (healthy)
devskyy-app          Up 35 hours (healthy)
devskyy-postgres     Up 35 hours (healthy)
devskyy-redis        Up 35 hours (healthy)
devskyy|PostgreSQL 15.18 on aarch64-unknown-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit
PONG

Two lessons in that output. First, redis-cli ping without the password returns NOAUTH Authentication required. — observed in the same session; the healthcheck at docker-compose.yml:94 passes -a "$$REDIS_PASSWORD" precisely because of this, and a hand-run probe that omits it looks like an outage that is not there. Second, the service names in exec commands are container names (devskyy-postgres), while in-network DNS uses the service name (postgres) — mixing them up is the most common "networking is broken" false alarm.

Anti-Patterns

# BAD: Using docker compose in production without orchestration
# Use Kubernetes, ECS, or Docker Swarm for production multi-container workloads

# BAD: Storing data in containers without volumes
# Containers are ephemeral -- all data lost on restart without volumes

# BAD: Running as root
# Always create and use a non-root user

# BAD: Using :latest tag
# Pin to specific versions for reproducible builds

# BAD: One giant container with all services
# Separate concerns: one process per container

# BAD: Putting secrets in docker-compose.yml
# Use .env files (gitignored) or Docker secrets