paulkinlan Dockerfile Authoring
When to Use
Use this skill when tasked with writing or improving a Dockerfile for any project.
Best Practices Reference
| Practice | Why | How |
|---|---|---|
| Order layers by change frequency | Faster builds via cache hits | Static deps first, source code last |
| Minimize layers | Smaller image, fewer attack surfaces | Combine RUN with && and \ |
| Use specific base image tags | Reproducible builds | node:20.11-slim not node:latest |
| Run as non-root user | Limit container compromise impact | Add USER directive |
| Multi-stage builds | Smaller final image | Build in one stage, copy artifacts to slim stage |
| Copy manifests before source | Cache dependency install layer | COPY package*.json first, then npm install |
| Always add HEALTHCHECK | Enable orchestrator monitoring | HEALTHCHECK CMD curl or process check |
| Use .dockerignore | Prevent leaking secrets, speed up context | Ignore .git, node_modules, .env |
Procedure
1. Determine Requirements
# What language/runtime?
PROJECT_DIR="${1:-~/workspace}"
ls "$PROJECT_DIR/package.json" "$PROJECT_DIR/pyproject.toml" "$PROJECT_DIR/Cargo.toml" \
"$PROJECT_DIR/go.mod" "$PROJECT_DIR/Makefile" 2>/dev/null
# What does the project need to run?
cat "$PROJECT_DIR/package.json" 2>/dev/null | jq '{main, scripts, engines}'
cat "$PROJECT_DIR/pyproject.toml" 2>/dev/null | head -20
# What system packages are required?
grep -rh 'apt-get\|apk add\|yum install' "$PROJECT_DIR/Dockerfile" 2>/dev/null
2. Write the Dockerfile
Node.js Application:
# Build stage
FROM node:20.11-slim AS build
WORKDIR /app
# Copy dependency manifests first (cacheable layer)
COPY package.json package-lock.json ./
RUN npm ci --production=false
# Copy source code (changes frequently — last layer)
COPY src/ ./src/
COPY tsconfig.json ./
# Build if needed
RUN npm run build 2>/dev/null || true
# Production stage
FROM node:20.11-slim
# Security: non-root user
RUN groupadd -r appuser && useradd -r -g appuser -d /app appuser
WORKDIR /app
# Copy only production dependencies
COPY package.json package-lock.json ./
RUN npm ci --production && npm cache clean --force
# Copy built application
COPY --from=build /app/dist/ ./dist/
COPY --from=build /app/src/ ./src/
# Set ownership
RUN chown -R appuser:appuser /app
USER appuser
# Expose port
EXPOSE 3000
# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))" || exit 1
CMD ["node", "src/index.js"]
Python Application:
# Build stage
FROM python:3.12-slim AS build
WORKDIR /app
# Install build dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
# Production stage
FROM python:3.12-slim
# Security: non-root user
RUN groupadd -r appuser && useradd -r -g appuser -d /app appuser
WORKDIR /app
# Copy installed packages from build stage
COPY --from=build /install /usr/local
# Copy application code
COPY src/ ./src/
# Set ownership
RUN chown -R appuser:appuser /app
USER appuser
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
CMD ["python3", "-m", "src.main"]
3. Write .dockerignore
cat > "$PROJECT_DIR/.dockerignore" <<'EOF'
.git
.gitignore
node_modules
.venv
__pycache__
*.pyc
.env
.env.*
*.md
.DS_Store
coverage/
.nyc_output/
tests/
test/
docs/
.idea/
.vscode/
*.log
Dockerfile
docker-compose*.yml
EOF
4. Validate the Dockerfile
DOCKERFILE="${PROJECT_DIR}/Dockerfile"
echo "=== Dockerfile Lint ==="
# Check for latest tag
grep -n ':latest' "$DOCKERFILE" && echo "WARNING: Using :latest tag — pin to specific version"
# Check for root user
grep -q 'USER' "$DOCKERFILE" && echo "OK: USER directive found" || echo "WARNING: No USER directive — runs as root"
# Check for HEALTHCHECK
grep -q 'HEALTHCHECK' "$DOCKERFILE" && echo "OK: HEALTHCHECK found" || echo "WARNING: No HEALTHCHECK"
# Check for .dockerignore
[ -f "$PROJECT_DIR/.dockerignore" ] && echo "OK: .dockerignore exists" || echo "WARNING: No .dockerignore"
# Check for COPY before RUN npm/pip install (caching)
COPY_LINE=$(grep -n 'COPY.*package\|COPY.*requirements' "$DOCKERFILE" | head -1 | cut -d: -f1)
INSTALL_LINE=$(grep -n 'RUN.*npm\|RUN.*pip' "$DOCKERFILE" | head -1 | cut -d: -f1)
if [ -n "$COPY_LINE" ] && [ -n "$INSTALL_LINE" ]; then
if [ "$COPY_LINE" -lt "$INSTALL_LINE" ]; then
echo "OK: Manifests copied before install (good caching)"
else
echo "WARNING: Install runs before manifest copy — poor caching"
fi
fi
# Check for multi-stage
grep -c 'FROM' "$DOCKERFILE" | xargs -I{} echo "Stages: {}"
[ "$(grep -c 'FROM' "$DOCKERFILE")" -gt 1 ] && echo "OK: Multi-stage build" || echo "INFO: Single-stage build"
# Check for secrets
grep -niE '(ENV|ARG).*(PASSWORD|SECRET|KEY|TOKEN)' "$DOCKERFILE" \
&& echo "WARNING: Possible secret in ENV/ARG — use runtime env or secrets mount"
# Try building (if docker available)
if which docker >/dev/null 2>&1; then
echo ""
echo "=== Build Test ==="
cd "$PROJECT_DIR"
docker build --no-cache -t test-build . 2>&1 | tail -10
echo "Build exit code: $?"
fi
5. Optimize Image Size
if which docker >/dev/null 2>&1; then
echo "=== Image Size ==="
docker images test-build --format '{{.Size}}' 2>/dev/null
echo ""
echo "=== Layer Analysis ==="
docker history test-build --no-trunc --format '{{.Size}}\t{{.CreatedBy}}' 2>/dev/null | head -15
fi
Quality Checklist
- Base image uses specific version tag (not :latest)
- Multi-stage build used (build deps not in final image)
- Dependency manifests copied before source code (layer caching)
- RUN commands combined with && to minimize layers
- Non-root USER directive present
- HEALTHCHECK directive present with appropriate interval
- .dockerignore excludes .git, node_modules, .env, tests
- No secrets in ENV or ARG directives
- Image builds successfully
- Final image size is reasonable for the application type