docker-best-practices

Docker Best Practices Skill

When to Use

Use this skill when:

• Creating new Dockerfiles
• Optimizing existing container images
• Setting up docker-compose environments
• Implementing health checks
• Securing container deployments
• Reducing image sizes
• Configuring multi-stage builds

Dockerfile Patterns

1. Multi-Stage Build (Python)

# Stage 1: Builder
FROM python:3.12-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Stage 2: Runtime
FROM python:3.12-slim AS runtime

WORKDIR /app

# Create non-root user
RUN groupadd -r appgroup && useradd -r -g appgroup appuser

# Copy wheels from builder
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/* && rm -rf /wheels

# Copy application
COPY --chown=appuser:appgroup . .

# Switch to non-root user
USER appuser

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

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

2. Layer Caching Optimization

# ✅ Good: Dependencies first (cached if unchanged)
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# ❌ Bad: Entire context first (cache invalidated on any change)
COPY . .
RUN pip install -r requirements.txt

3. Security Hardening

# ✅ Security checklist:
# 1. Non-root user
USER appuser

# 2. Read-only filesystem
# docker run --read-only ...

# 3. No new privileges
# docker run --security-opt=no-new-privileges ...

# 4. Drop capabilities
# docker run --cap-drop=ALL ...

# 5. Minimal base image
FROM python:3.12-alpine  # or distroless

# 6. No secrets in image
# Use environment variables or secrets mount