Index of every page on this site: llms.txt
All skills
rknall avatar

/docker-validation

@ca7fbd0
by Roland Knallrknall/claude-skills93 stars
13
Run it yourself

Comprehensive Docker and Docker Compose validation following best practices and security standards. Use this skill when users ask to validate Dockerfiles, review Docker configurations, check Docker Compose files, verify multi-stage builds, audit Docker security, or ensure compliance with Docker best practices. Validates syntax, security, multi-stage builds, and modern Docker Compose requirements.

  • 4 files
  • 52.8 KB
  • Updated last year
  • GitHub
Use this Skill: https://skilld.dev/gh/rknall/claude-skills/docker-validation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

validation-checklist.md

≈2.9k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Docker Validation Checklist

Complete checklist for validating Docker configurations. Use this as a reference when performing manual validation.

Dockerfile Validation Checklist

Base Image (Critical)

  • No :latest tags used
  • Specific version pinned (e.g., node:20.11.0-alpine)
  • Uses minimal base image (alpine, slim, or distroless variants)
  • Trusted registry used (docker.io, ghcr.io, gcr.io, quay.io)
  • Base image is actively maintained and supported

Multi-Stage Build (High Priority)

  • At least 2 stages for production builds (build + runtime)
  • All stages named with AS keyword
  • Artifacts copied between stages using COPY --from=
  • Final stage uses minimal base image
  • Build tools NOT present in final stage
  • Only necessary files in final image

Security (Critical)

  • USER directive present (non-root user specified)
  • Last USER is NOT root or 0
  • No secrets in ENV variables
  • No secrets in COPY/ADD commands
  • No secrets in RUN commands
  • No hardcoded passwords or API keys
  • Uses --chown when copying files for non-root user

Directory & Paths (High Priority)

  • WORKDIR uses absolute paths (not relative)
  • No use of cd in RUN commands
  • .dockerignore file present
  • Build context is minimal (excludes unnecessary files)

Layer Optimization (Medium Priority)

  • RUN commands combined where logical (using &&)
  • Package manager cache cleaned (apt, apk, yum)
  • Dependency files copied before source code (for better caching)
  • Multi-line commands use backslash continuation
  • No unnecessary layers created

Package Management (High Priority)

  • Package versions pinned (apt-get, apk, yum)
  • Package cache cleaned after installation
  • Uses --no-install-recommends for apt-get
  • Uses --virtual for build dependencies in alpine
  • Python: Versions pinned in requirements.txt
  • Node: Uses npm ci instead of npm install

Best Practices (Medium Priority)

  • HEALTHCHECK instruction defined
  • Uses COPY instead of ADD (unless extracting archives)
  • CMD and ENTRYPOINT use JSON notation
  • Labels included (maintainer, version, description)
  • Appropriate EXPOSE directives for documented ports
  • ENV variables clearly defined
  • Build args used for customization points

Documentation (Low Priority)

  • Comments explain complex operations
  • Each stage has descriptive comment
  • Unusual patterns are documented
  • Maintainer/author documented in labels

Hadolint Rule Reference

Rule Description Severity Check
DL3000 Use absolute WORKDIR Error [ ]
DL3001 Some commands should not be used Warning [ ]
DL3002 Last USER should not be root Error [ ]
DL3003 Use WORKDIR to switch directories Warning [ ]
DL3006 Always tag image explicitly Warning [ ]
DL3007 Using latest is prone to errors Warning [ ]
DL3008 Pin versions in apt-get install Warning [ ]
DL3009 Delete apt-get lists after installing Info [ ]
DL3013 Pin versions in pip Warning [ ]
DL3014 Use -y flag with apt-get Warning [ ]
DL3015 Avoid additional packages Info [ ]
DL3016 Pin versions in npm Warning [ ]
DL3018 Pin versions in apk add Warning [ ]
DL3019 Use --no-cache with apk add Info [ ]
DL3020 Use COPY instead of ADD Error [ ]
DL3022 COPY --from should reference stage Error [ ]
DL3025 Use JSON for CMD and ENTRYPOINT Warning [ ]

Docker Compose Validation Checklist

Modern Syntax (Critical)

  • NO version field present (obsolete since Compose v2.27.0)
  • File uses modern Compose Specification syntax
  • Compatible with Docker Compose v2.27.0+

Service Configuration (High Priority)

  • All services have specific image tags (no :latest)
  • Restart policies defined (restart: unless-stopped)
  • Service dependencies specified (depends_on)
  • Container names specified (optional but recommended)
  • All services have descriptive names (kebab-case)

Health Checks (High Priority)

  • Critical services have health checks
  • Health check intervals are reasonable
  • Health check timeout values appropriate
  • Start period allows for initialization
  • Retries configured for reliability

Resource Management (Medium Priority)

  • Resource limits defined (memory, CPU)
  • Resource reservations specified
  • PID limits set (if applicable)
  • Ulimits configured (if needed)

Networking (High Priority)

  • Custom networks defined (not default bridge)
  • Network drivers specified
  • Network isolation implemented
  • Port mappings use host IP when needed
  • Internal networks used for backend services

Volumes & Persistence (High Priority)

  • Named volumes used for persistence
  • Volume drivers specified
  • Bind mounts use absolute paths
  • Volume permissions appropriate
  • No sensitive data in bind mounts
  • Volumes section defines named volumes

Environment & Configuration (Critical)

  • Environment variables properly defined
  • No hardcoded secrets in compose file
  • .env file used for configuration
  • Secrets managed with Docker secrets or external
  • ENV files specified with env_file

Security (Critical)

  • No privileged: true (unless absolutely necessary)
  • Capabilities properly configured
  • User/group specified for services
  • Read-only root filesystem (where applicable)
  • Security options configured
  • AppArmor/SELinux profiles defined

Logging (Medium Priority)

  • Logging drivers configured
  • Log rotation configured
  • Log size limits set
  • Appropriate log drivers for environment

Build Configuration (if using build)

  • Build context clearly specified
  • Build args defined if needed
  • Dockerignore file present
  • Target stage specified for multi-stage
  • Cache from configured for faster builds

Multi-Stage Build Specific Checks

Stage Structure

  • Build stage uses full toolchain image
  • Build stage installs ALL dependencies
  • Build stage compiles/builds artifacts
  • Runtime stage uses minimal image
  • Runtime stage copies only artifacts
  • Runtime stage installs only runtime deps

Node.js Multi-Stage

  • Build stage: npm ci (not npm install)
  • Build stage: npm run build
  • Build stage: npm run test (optional)
  • Runtime stage: npm ci --only=production
  • Runtime stage: Copies from builder dist/build folder
  • Runtime stage: Uses alpine variant

Python Multi-Stage

  • Build stage: Compiles wheels
  • Build stage: Installs build dependencies
  • Build stage: Creates virtual environment
  • Runtime stage: Installs pre-built wheels
  • Runtime stage: Minimal Python image (alpine/slim)
  • Runtime stage: No compiler or build tools

Go Multi-Stage

  • Build stage: Full Go image
  • Build stage: CGO_ENABLED=0 for static binary
  • Build stage: Builds binary
  • Runtime stage: scratch or distroless
  • Runtime stage: Only binary copied
  • Runtime stage: Certificates copied if needed

Security Checklist

Image Security

  • Base images scanned for vulnerabilities
  • No images older than 6 months without review
  • Images from trusted sources only
  • Image digests used for critical deployments
  • Regular security updates applied

Runtime Security

  • Runs as non-root user (UID > 0)
  • Minimal capabilities granted
  • No unnecessary privileges
  • Read-only root filesystem where possible
  • Temporary directories properly configured

Network Security

  • Only necessary ports exposed
  • Internal networks for backend communication
  • No host network mode (unless required)
  • Firewall rules configured
  • TLS/SSL for external communications

Data Security

  • No secrets in image layers
  • Secrets managed via secrets management
  • Sensitive volumes properly protected
  • Encryption at rest configured
  • Backup strategy for persistent data

Access Control

  • Least privilege principle applied
  • Appropriate user permissions
  • No root access to containers
  • Host resources properly isolated
  • Volume mounts restricted

CI/CD Integration Checklist

Pre-commit Validation

  • Pre-commit hook validates Dockerfiles
  • Pre-commit hook checks Compose files
  • Hook checks for obsolete version field
  • Hook runs Hadolint/DCLint
  • Hook prevents commits with critical issues

Pipeline Validation

  • Hadolint runs on all Dockerfiles
  • Docker Compose config validation
  • DCLint runs on Compose files
  • Security scanning integrated (Trivy, Snyk)
  • Build tests before merge
  • Automated PR comments with issues

Deployment Validation

  • Validation runs before deployment
  • Rollback on validation failure
  • Health checks verified post-deployment
  • Smoke tests after deployment
  • Monitoring alerts configured

Common Issue Quick Reference

❌ Using :latest Tag

Check: grep -r ":latest" Dockerfile docker-compose.yml Fix: Pin specific version (e.g., nginx:1.24-alpine)

❌ Obsolete Version Field

Check: grep "^version:" docker-compose.yml Fix: Remove the entire version: line

❌ Running as Root

Check: grep "^USER" Dockerfile | tail -1 Fix: Add USER <non-root-user> before CMD/ENTRYPOINT

❌ No Multi-Stage Build

Check: grep -c "^FROM" Dockerfile Fix: Implement at least 2 stages

❌ Package Cache Not Cleaned

Check: Look for apt/apk without cleanup Fix: Add rm -rf /var/lib/apt/lists/* or --no-cache

❌ Using ADD Instead of COPY

Check: grep "^ADD" Dockerfile Fix: Replace with COPY unless extracting archives

❌ No Health Check

Check: grep "HEALTHCHECK" Dockerfile Fix: Add appropriate HEALTHCHECK instruction

❌ No Restart Policy

Check: grep "restart:" docker-compose.yml Fix: Add restart: unless-stopped to services

Validation Priority Matrix

Priority Dockerfile Docker Compose Multi-Stage Security
CRITICAL No :latest, USER set No version field N/A Non-root user
HIGH HEALTHCHECK, WORKDIR Restart policy, Health checks 2+ stages No secrets
MEDIUM Layer optimization Resource limits Named stages Minimal image
LOW Comments, Labels Logging config Optimization Hardening

Tool-Specific Validation

Hadolint Configuration (.hadolint.yaml)

ignored:
  - DL3008  # Pin apt versions (too strict for some use cases)
override:
  error:
    - DL3002  # Last USER must not be root
    - DL3020  # Use COPY not ADD
trustedRegistries:
  - docker.io
  - ghcr.io
  - gcr.io

DCLint Configuration (.dclintrc.json)

{
  "rules": {
    "no-version-field": "error",
    "require-quotes": "warning",
    "no-duplicate-keys": "error"
  }
}

Quick Validation Commands

# Validate Dockerfile
hadolint Dockerfile

# Validate Docker Compose
docker compose config --quiet

# Check for obsolete version field
grep "^version:" docker-compose.yml

# Count FROM statements (multi-stage check)
grep -c "^FROM" Dockerfile

# Check final USER
grep "^USER" Dockerfile | tail -1

# Find :latest tags
grep -r ":latest" .

# Full validation
./validate-docker.sh

Use this checklist to ensure comprehensive validation of all Docker configurations.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at ca7fbd0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Dormantupdated last year

README badge

README badge for rknall/claude-skills/docker-validation