Docker Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: docker for comprehensive documentation.

Dockerfile (Node.js)

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./

USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]

Dockerfile (Python)

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

USER nobody
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Common Commands

# Build
docker build -t myapp:latest .
docker build -f Dockerfile.prod -t myapp:prod .

# Run
docker run -d -p 3000:3000 --name myapp myapp:latest
docker run --env-file .env myapp:latest

# Manage
docker ps                    # List running
docker logs myapp           # View logs
docker exec -it myapp sh    # Shell access
docker stop myapp           # Stop container
docker rm myapp             # Remove container

# Images
docker images               # List images
docker rmi myapp:latest     # Remove image
docker system prune         # Clean up

Best Practices

Do	Don't
Multi-stage builds	Run as root
Use .dockerignore	Copy node_modules
Specific base image tags	Use latest in prod
One process per container	Install unnecessary packages
Layer caching (COPY package.json first)	Hardcode secrets

.dockerignore

node_modules
.git
.env*
dist
*.log

When NOT to Use This Skill

Skip this skill when:

• Managing multi-container applications with docker-compose.yml - use docker-compose skill
• Orchestrating containers in Kubernetes - use kubernetes skill
• CI/CD pipeline automation - use github-actions skill
• Only running third-party images without creating Dockerfiles
• Using container platforms that abstract Docker (e.g., Heroku, Google Cloud Run config)

Anti-Patterns

Anti-Pattern	Problem	Solution
Using :latest in production	Unpredictable deployments	Pin specific versions node:20.10.0-alpine
Running as root	Security vulnerability	Use USER node or create non-root user
Copying node_modules/	Slow builds, platform issues	Add to .dockerignore, run npm ci in container
Installing dev dependencies	Bloated images	Use npm ci --only=production
No multi-stage builds	Large production images	Separate build and runtime stages
Hardcoding secrets in ENV	Secret exposure in image layers	Use Docker secrets or mount at runtime
Single RUN per command	Excessive layers	Chain related commands with &&
Not using .dockerignore	Slow context transfer	Exclude unnecessary files
Installing unnecessary packages	Attack surface, image size	Install only required packages
No health checks	Unhealthy containers keep running	Add HEALTHCHECK directive

Quick Troubleshooting

Issue	Diagnosis	Fix
Build is slow	Large build context	Add .dockerignore, optimize layer caching
Image size too large	Dev dependencies, multiple stages	Multi-stage build, --only=production
"Permission denied" in container	Running as root, wrong file ownership	Use USER directive, COPY --chown
Build cache not working	COPY before dependency install	Copy package.json first, then install, then code
Container crashes immediately	Wrong CMD/ENTRYPOINT, missing deps	Check logs: docker logs <container>
Can't connect to database	Wrong network, wrong host	Use service name as host, check network
"Exec format error"	Wrong platform (ARM vs x86)	Build for correct platform: --platform linux/amd64
Port not accessible	Not exposed or published	Use EXPOSE + docker run -p
Files not updating	Cached layers	Clear cache: docker build --no-cache
Volume data persists after deletion	Named volumes not removed	Use docker volume rm or docker-compose down -v

Production Readiness

Security Configuration

# Security-hardened Dockerfile
FROM node:20-alpine AS builder

# Create non-root user
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

# Production image
FROM node:20-alpine

# Security: install security updates
RUN apk update && apk upgrade && rm -rf /var/cache/apk/*

# Create non-root user
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

WORKDIR /app

# Copy with correct ownership
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./

# Drop privileges
USER appuser

# Security: read-only filesystem (use with docker run --read-only)
# Make /tmp writable if needed
VOLUME ["/tmp"]

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

EXPOSE 3000
CMD ["node", "dist/index.js"]

Image Scanning

# Scan for vulnerabilities
docker scout cves myapp:latest
docker scout recommendations myapp:latest

# Alternative: Trivy scanner
trivy image myapp:latest

# Scan during CI/CD
docker build -t myapp:latest .
trivy image --exit-code 1 --severity HIGH,CRITICAL myapp:latest

Resource Limits

# docker-compose.yml with limits
services:
  app:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    # Security options
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

# Run with limits
docker run -d \
  --memory=512m \
  --memory-swap=512m \
  --cpus=1.0 \
  --read-only \
  --tmpfs /tmp \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL \
  myapp:latest

Secrets Management

# docker-compose.yml with secrets
services:
  app:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
    environment:
      - DB_PASSWORD_FILE=/run/secrets/db_password

secrets:
  db_password:
    external: true  # Or use file: ./secrets/db_password.txt
  api_key:
    external: true

// Read secrets in application
import { readFileSync } from 'fs';

const dbPassword = process.env.DB_PASSWORD_FILE
  ? readFileSync(process.env.DB_PASSWORD_FILE, 'utf8').trim()
  : process.env.DB_PASSWORD;

Health Checks

# Dockerfile health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

# docker-compose.yml health check
services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

Logging Best Practices

# docker-compose.yml logging
services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
        labels: "service,environment"
        tag: "{{.Name}}/{{.ID}}"

# View logs with timestamps
docker logs --timestamps --tail 100 myapp

# Follow logs
docker logs -f myapp

# Logs from all containers
docker-compose logs -f --tail=100

Network Security

# docker-compose.yml network isolation
services:
  app:
    networks:
      - frontend
      - backend

  db:
    networks:
      - backend  # Not accessible from frontend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # No external access

Monitoring Metrics

Metric	Alert Threshold
Container CPU usage	> 80%
Container memory usage	> 80%
Container restart count	> 3 in 5 minutes
Health check failures	> 0
Image vulnerabilities (critical)	> 0

Production Commands

# Cleanup unused resources
docker system prune -af --volumes

# Monitor resources
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# Check container health
docker inspect --format='{{.State.Health.Status}}' myapp

# Update without downtime (with docker-compose)
docker-compose pull
docker-compose up -d --no-deps --build app

Checklist

• Non-root user in container
• Multi-stage build (minimal final image)
• .dockerignore configured
• Specific base image tags (not :latest)
• Security updates installed
• Image vulnerability scanning
• Resource limits (CPU/memory)
• Read-only root filesystem
• Capabilities dropped
• Secrets via Docker secrets (not ENV)
• Health checks configured
• Log rotation configured
• Network isolation
• No sensitive data in image

Reference Documentation

• Multi-stage Builds
• Security