Skip to content
docker-patterns logo

Docker Patterns

docker-patterns

Docker and Docker Compose patterns for local development, container security, networking, volume strategies, and multi-service orchestration.

affaan-m/ecc12.7Kinstalls273.3Kstars

SKILL.md

Full skill instructions

Docker Patterns

Docker and Docker Compose best practices for containerized development.

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:
      - pgdata:/​var/​lib/​postgresql/​data
      - ./​scripts/​init-db.sql:/​docker-entrypoint-initdb.d/​init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/​data

  mailpit:                            # Local email testing
    image: axllent/​mailpit
    ports:
      - "8025:8025"                   # Web UI
      - "1025:1025"                   # SMTP

volumes:
  pgdata:
  redisdata:

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

Hardened CLI Installer Harnesses

Use containers to test installer behavior against disposable project copies without allowing the test to mutate the source checkout.

Respect the Platform Boundary

  • Run real containers for Linux distributions such as Debian and Ubuntu.
  • macOS cannot run as a Docker container because Docker shares a Linux kernel. Run the same shell-free test entry point natively on macOS.
  • Windows containers require a Windows Docker engine. Run platform-independent logic on a native Windows CI runner and reserve Windows containers for a Windows host.
  • Keep a native Ubuntu/​macOS/​Windows CI matrix for host-specific paths, command shims, quoting, and filesystem behavior.

Do not claim that a Linux container validates macOS or Windows behavior.

Enforce the Isolation Contract

  • Pin base images by immutable digest and pin installed CLI versions.
  • Run as a non-root numeric UID/​GID when distro account names differ.
  • Mount the repository and source project read-only.
  • Copy the source project into a writable tmpfs workspace before any mutation.
  • Mount /​workspace with noexec, UID/​GID 1000, and mode=0700 so only the container user can inspect project data.
  • Keep npm and npx's executable cache at NPM_CONFIG_CACHE=/​tmp/​npm-cache on the executable /​tmp mount. Its default size is 2 GiB and can be adjusted with ECC_TMPFS_SIZE; ECC_WORKSPACE_SIZE separately controls the private workspace mount.
  • Set read_only: true, no-new-privileges:true, cap_drop: [ALL], and a finite pids_limit.
  • Keep the default real-CLI services on network_mode: none. Add network access only through a visibly named opt-in service for an authenticated provider session; never make it an accidental environment-driven default.
  • Create only the writable temporary paths the tool needs.
  • Do not pass host credentials into the container by default.
  • Default to a dry run and whitelist only the explicit dry-run, install, plugin, and shell modes.
  • Use argument arrays or spawnSync(..., { shell: false }) for cross-platform runners. Never interpolate project paths into a shell command.

Exercise the ECC Plugin Setup Harness

Use docker/​plugin-setup/​compose.yaml as the reference implementation. It provides:

  • fixture-tests for the focused install manifest, target, and executor suite.
  • real-cli for the pinned Debian-based generic Linux image.
  • real-cli-ubuntu for the pinned Ubuntu image.

Validate the Compose model before building:

docker compose -f docker/​plugin-setup/​compose.yaml config --quiet

Build both real Linux images:

docker compose -f docker/​plugin-setup/​compose.yaml \
  build real-cli real-cli-ubuntu

Run the safe default flow in each image:

docker compose -p ecc-plugin-debian-test \
  -f docker/​plugin-setup/​compose.yaml \
  run --rm -T real-cli dry-run

docker compose -p ecc-plugin-ubuntu-test \
  -f docker/​plugin-setup/​compose.yaml \
  run --rm -T real-cli-ubuntu dry-run

The dry run executes the current public command contract:

ecc install --profile core --target claude-project --dry-run --json

Before that command runs, the container creates a locally packed npm artifact from the read-only checkout with npm pack --ignore-scripts. It extracts the self-created tarball under /​tmp, validates the ecc-universal package name, required install manifests, and the confined package.json bin.ecc mapping, then invokes the extracted ecc executable. The runtime stays on network_mode: none, does not execute package lifecycle scripts, and does not rely on host node_modules; its exact pinned production dependencies are already present in the image.

The harness rejects an empty plan, a non-claude-project target, any operation outside /​workspace/​project/​.claude, or any dry run that creates the target directory. install performs the isolated apply twice, checks its managed install state, lists the installed target, and runs doctor.

Start, Open, Reconnect, and Clean Up a Named Session

Start a detached container without --rm so leaving a terminal does not remove the session:

docker compose -p ecc-plugin-session \
  -f docker/​plugin-setup/​compose.yaml \
  run --detach --name ecc-plugin-shell real-cli shell

The container copies the read-only fixture to the stable private directory /​workspace/​project. Confirm it is running, then emit the Docker side of the terminal-opener v1 data contract:

docker inspect --format '{{.State.Running}}' ecc-plugin-shell
node docker/​plugin-setup/​interactive-plan.js \
  --container ecc-plugin-shell \
  --workdir /​workspace/​project \
  --json \
  -- bash

The JSON result has exactly an executable and argv boundary (plus contractVersion: 1): the executable is docker, and argv begins with exec, -it, and -w. Pass that data to the separate terminal-opener skill when it is installed. This Docker harness deliberately does not import a terminal adapter, interpolate a shell command, or manage a host GUI process. Until then, open the same PTY in the current host terminal directly:

docker exec -it -w /​workspace/​project ecc-plugin-shell bash

Exit the shell without stopping the detached container. Reconnect with the same docker exec -it command. When finished, remove the exact named container and its Compose project resources:

docker rm --force ecc-plugin-shell
docker compose -p ecc-plugin-session \
  -f docker/​plugin-setup/​compose.yaml \
  down --remove-orphans

Host credentials are absent by default and credential directories are never mounted. The default service also has no network access. When an authenticated provider session genuinely needs a network, build real-cli first and then opt in visibly with docker compose --profile networked run real-cli-networked shell. Prefer authenticating inside that disposable session. If a CI run must inherit a host environment credential, make that opt-in at invocation with an explicit Compose --env NAME flag, understand that the value is inspectable and can be exfiltrated for the container lifetime, and remove the exact named container immediately after.

Run the same focused suite natively on the host:

npm run test:plugin-setup-platform

Inspect the produced identity and environment before trusting the image:

docker image inspect ecc-plugin-setup:debian ecc-plugin-setup:ubuntu

Clean each named test project without deleting unrelated volumes or images:

docker compose -p ecc-plugin-debian-test \
  -f docker/​plugin-setup/​compose.yaml down --remove-orphans
docker compose -p ecc-plugin-ubuntu-test \
  -f docker/​plugin-setup/​compose.yaml down --remove-orphans

.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

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

More skills from affaan-m

coding-standards logo
affaan-m/ecc

coding-standards

Baseline cross-project coding conventions for naming, readability, immutability, and code-quality review. Use detailed frontend or backend skills for framework-specific patterns.

273.3K 14K
View
golang-testing logo
affaan-m/ecc

golang-testing

Go testing patterns including table-driven tests, subtests, benchmarks, fuzzing, and test coverage. Follows TDD methodology with idiomatic Go practices.

273.3K 13.1K
View

Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.

273.3K 12.2K
View
video-editing logo
affaan-m/ecc

video-editing

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

273.3K 12.2K
View
python-patterns logo
affaan-m/ecc

python-patterns

Pythonic idioms, PEP 8 standards, type hints, and best practices for building robust, efficient, and maintainable Python applications.

273.3K 12.1K
View
frontend-slides logo
affaan-m/ecc

frontend-slides

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

273.3K 12.1K
View
api-design logo
affaan-m/ecc

api-design

REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.

273.3K 11.9K
View
django-patterns logo
affaan-m/ecc

django-patterns

Django architecture patterns, REST API design with DRF, ORM best practices, caching, signals, middleware, and production-grade Django apps.

273.3K 11.9K
View
postgres-patterns logo
affaan-m/ecc

postgres-patterns

PostgreSQL database patterns for query optimization, schema design, indexing, and security. Based on Supabase best practices.

273.3K 11.9K
View
tdd-workflow logo
affaan-m/ecc

tdd-workflow

Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.

273.3K 11.6K
View
prompt-optimizer logo
affaan-m/ecc

prompt-optimizer

Analyze raw prompts, identify intent and gaps, match ECC components (skills/commands/agents/hooks), and output a ready-to-paste optimized prompt. Advisory role only — never executes the task itself. TRIGGER when: user says "optimize prompt", "improve my prompt", "how to write a prompt for", "help me prompt", "rewrite this prompt", or explicitly asks to enhance prompt quality. Also triggers on Chinese equivalents: "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令". DO NOT TRIGGER when: user wants the task executed directly, or says "just do it" / "直接做". DO NOT TRIGGER when user says "优化代码", "优化性能", "optimize performance", "optimize this code" — those are refactoring/performance tasks, not prompt optimization.

273.3K 11.3K
View

Java coding standards for Spring Boot and Quarkus services: naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout. Automatically applies framework-specific conventions.

273.3K 11.3K
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View