dockerfile-best-practiceslisted
Install: claude install-skill obeone/claude-skills
# Dockerfile Best Practices
Comprehensive guide for creating optimized, secure, and fast Docker images using modern BuildKit features.
## Workflow
1. **Identify language/framework** → Pick template from [Language Templates](#language-templates)
2. **Apply essential rules** → Every Dockerfile must follow [Essential Rules](#essential-rules)
3. **Security hardening** → Non-root user, pin versions, secrets management
4. **Optimize for cache** → Separate deps from code, use cache mounts
5. **Multi-stage if needed** → Compiled languages or distroless runtime
6. **Add metadata** → OCI labels, HEALTHCHECK, STOPSIGNAL
7. **Review** → Run `scripts/analyze_dockerfile.py` or `scripts/analyze_compose.py`
## Essential Rules (Always Apply)
### 1. BuildKit syntax directive (first line, always)
```dockerfile
# syntax=docker/dockerfile:1
```
### 2. Pin runtime versions, NOT OS versions
```dockerfile
# ✅ GOOD
FROM python:3.12-slim
FROM node:22-alpine
FROM golang:1-alpine
# ❌ BAD - pins OS, blocks security updates
FROM python:3.12-slim-bookworm
FROM node:22-alpine3.19
```
### 3. Cache mounts for all package managers
```dockerfile
# pip
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
# npm
RUN --mount=type=cache,target=/root/.npm npm ci
# yarn
RUN --mount=type=cache,target=/root/.yarn yarn install --frozen-lockfile
# go
RUN --mount=type=cache,target=/go/pkg/mod go mod download
# cargo
RUN --mount=type=cache,target=/usr/local/cargo/registry cargo build