Docker Configuration Validator

Docker Configuration Validator

This skill provides comprehensive validation for Dockerfiles and Docker Compose files, ensuring compliance with best practices, security standards, and modern syntax requirements.

When to Use This Skill

Activate this skill when the user requests:

• Validate Dockerfiles or Docker Compose files
• Review Docker configurations for best practices
• Check for Docker security issues
• Verify multi-stage build implementation
• Audit Docker setup for production readiness
• Ensure modern Docker Compose syntax compliance
• Fix Docker configuration issues
• Create validation scripts or CI/CD integration

Core Workflow

Phase 1: Initial Assessment

When a user requests Docker validation, start by understanding the scope:

1. Identify What to Validate

• Single Dockerfile or multiple?
• Docker Compose file(s)?
• Entire project directory?
• Specific concerns or focus areas?
• Production vs development environment?

2. Understand Requirements

• Security compliance level needed?
• Multi-stage build requirement?
• Performance constraints?
• CI/CD integration needed?
• Automated validation script desired?

3. Check Available Tools

• Is Hadolint available? (Dockerfile linter)
• Is DCLint available? (Docker Compose linter)
• Is Docker CLI available?
• Should tools be installed as part of process?

Phase 2: Dockerfile Validation

Step 1: Locate Dockerfiles

Find all Dockerfiles in the project:

find . -type f \( -name "Dockerfile*" ! -name "*.md" \)

Step 2: Run Hadolint Validation

If Hadolint is available:

# Validate each Dockerfile
hadolint Dockerfile

# JSON output for programmatic analysis
hadolint --format json Dockerfile

# Set failure threshold
hadolint --failure-threshold error Dockerfile

If Hadolint is NOT available:

• Perform manual validation using built-in checks (see Step 3)
• Recommend Hadolint installation
• Provide installation instructions

Step 3: Manual Dockerfile Validation

Check each Dockerfile for critical issues:

1. Base Image Best Practices

• ✅ Check: No :latest tags
• ✅ Check: Specific version pinned
• ✅ Check: Uses minimal base images (alpine/slim variants)
• ✅ Check: Trusted registry used

2. Multi-Stage Build Verification

# Count FROM statements (should be >= 2 for multi-stage)
FROM_COUNT=$(grep -c "^FROM " Dockerfile)

# Check for named stages
NAMED_STAGES=$(grep -c "^FROM .* AS " Dockerfile)

# Check for inter-stage copies
COPY_FROM=$(grep -c "COPY --from=" Dockerfile)

Analysis:

• If FROM_COUNT >= 2: Multi-stage build detected ✅
• If COPY_FROM == 0 and FROM_COUNT >= 2: Warning - artifacts may not be transferred
• If FROM_COUNT == 1: Single-stage build - recommend multi-stage for optimization

3. Security Checks

• ✅ Check: USER directive present (non-root)
• ✅ Check: Last USER is not root
• ✅ Check: No secrets in Dockerfile
• ✅ Check: WORKDIR uses absolute paths
• ✅ Check: No unnecessary privileges

4. Layer Optimization

• ✅ Check: Combined RUN commands
• ✅ Check: Package manager cache cleaned
• ✅ Check: COPY before RUN for better caching
• ✅ Check: .dockerignore file exists

5. Best Practices

• ✅ Check: HEALTHCHECK defined
• ✅ Check: WORKDIR used (not cd)
• ✅ Check: COPY preferred over ADD
• ✅ Check: CMD/ENTRYPOINT uses JSON notation
• ✅ Check: Labels included (maintainer, version)

Step 4: Dockerfile Issue Classification

Classify findings by severity:

CRITICAL (Must Fix):

• Running as root user
• Using :latest tags
• Secrets exposed in image
• Invalid syntax

HIGH (Should Fix):

• No multi-stage build when applicable
• No HEALTHCHECK
• Package versions not pinned
• Security vulnerabilities

MEDIUM (Recommended):

• Using ADD instead of COPY
• Not cleaning package cache
• Missing labels
• Inefficient layer structure

LOW (Nice to Have):

• Could use slimmer base image
• Could combine more RUN commands
• Could improve comments

Phase 3: Docker Compose Validation

Step 1: Locate Compose Files

Find all Docker Compose files:

find . -maxdepth 3 -type f \( -name "docker-compose*.yml" -o -name "docker-compose*.yaml" -o -name "compose*.yml" \)

Step 2: Check for Obsolete Version Field

CRITICAL CHECK: Modern Docker Compose (v2.27.0+) does NOT use version field

# Check for obsolete version field
if grep -q "^version:" docker-compose.yml; then
    echo "❌ ERROR: Found obsolete 'version' field"
    echo "Remove 'version:' line - it's obsolete in Compose v2.27.0+"
fi

Old (Deprecated):

version: '3.8'  # ❌ REMOVE THIS
services:
  web:
    image: nginx:latest

New (Modern):

# No version field!
services:
  web:
    image: nginx:1.24-alpine

Step 3: Built-in Docker Compose Validation

# Syntax validation
docker compose config --quiet

# Show resolved configuration
docker compose config

# Validate specific file
docker compose -f docker-compose.prod.yml config --quiet

Step 4: DCLint Validation (if available)

# Lint compose file
dclint docker-compose.yml

# Auto-fix issues
dclint --fix docker-compose.yml

# JSON output
dclint --format json docker-compose.yml

Step 5: Manual Compose Validation

1. Image Best Practices

• ✅ Check: No :latest tags
• ✅ Check: Specific versions specified
• ✅ Check: Images from trusted sources

2. Service Configuration

• ✅ Check: Restart policies defined
• ✅ Check: Health checks configured
• ✅ Check: Resource limits set (optional but recommended)
• ✅ Check: Proper service dependencies (depends_on)

3. Networking

• ✅ Check: Custom networks defined
• ✅ Check: Network isolation implemented
• ✅ Check: Appropriate network drivers used

4. Volumes & Persistence

• ✅ Check: Named volumes for persistence
• ✅ Check: Volume drivers specified
• ✅ Check: Bind mounts use absolute paths
• ✅ Check: No sensitive data in volumes

5. Environment & Secrets

• ✅ Check: Environment variables properly managed
• ✅ Check: No hardcoded secrets
• ✅ Check: .env file usage recommended
• ✅ Check: Secrets management configured

6. Security

• ✅ Check: No privileged mode (unless necessary)
• ✅ Check: Capabilities properly configured
• ✅ Check: User/group specified
• ✅ Check: Read-only root filesystem (where applicable)

Phase 4: Multi-Stage Build Deep Dive

When validating multi-stage builds, ensure:

1. Stage Structure

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

# Production stage
FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/index.js"]

2. Validation Checklist

• ✅ At least 2 stages (build + runtime)
• ✅ All stages are named with AS keyword
• ✅ Artifacts copied between stages using COPY --from
• ✅ Final stage uses minimal base image
• ✅ Build tools NOT in final stage
• ✅ Only necessary files in final image
• ✅ Final stage runs as non-root user

3. Common Patterns to Check

Node.js Multi-Stage:

• Build stage: Install all deps, build, test
• Runtime stage: Production deps only, built artifacts

Python Multi-Stage:

• Build stage: Compile dependencies, build wheels
• Runtime stage: Install pre-built wheels, app only

Go Multi-Stage:

• Build stage: Full Go toolchain, compile binary
• Runtime stage: Scratch/distroless, binary only

Phase 5: Security Audit

Perform comprehensive security checks:

1. User & Permissions

# Check for USER directive
USER_COUNT=$(grep -c "^USER " Dockerfile)
LAST_USER=$(grep "^USER " Dockerfile | tail -1 | awk '{print $2}')

if [ "$USER_COUNT" -eq 0 ]; then
    echo "❌ CRITICAL: No USER specified (runs as root!)"
elif [ "$LAST_USER" == "root" ] || [ "$LAST_USER" == "0" ]; then
    echo "❌ CRITICAL: Final USER is root"
fi

2. Exposed Secrets

• Check for passwords in ENV
• Check for API keys in COPY/ADD
• Check for credentials in RUN commands
• Recommend secrets management solutions

3. Vulnerable Base Images

• Check base image age and support status
• Recommend security scanning (Trivy, Snyk)
• Suggest pinned, supported versions

4. Network Exposure

• Review EXPOSE directives
• Check if unnecessary ports exposed
• Validate port mappings in Compose

Phase 6: Generate Validation Report

Structure the validation report:

# Docker Configuration Validation Report

## Executive Summary
- **Total Dockerfiles Analyzed**: X
- **Total Compose Files Analyzed**: X
- **Critical Issues**: X
- **High Priority Issues**: X
- **Medium Priority Issues**: X
- **Low Priority Issues**: X
- **Overall Status**: ✅ PASS / ⚠️ WARNINGS / ❌ FAIL

## Dockerfile Analysis

### [Dockerfile Path]

#### Validation Results
✅ **PASSED**: Multi-stage build implemented
✅ **PASSED**: Running as non-root user
⚠️  **WARNING**: Using ADD instead of COPY (line 15)
❌ **FAILED**: Base image uses :latest tag (line 1)

#### Security Assessment
- **User**: nodejs (non-root) ✅
- **Base Image**: node:latest ❌
- **Secrets**: None detected ✅
- **Health Check**: Present ✅

#### Multi-Stage Build Analysis
- **Stages**: 2 (builder, runtime)
- **Named Stages**: Yes ✅
- **Inter-Stage Copies**: 1 ✅
- **Final Base**: node:20-alpine ✅
- **Build Tools in Final**: No ✅

#### Issues Found

**CRITICAL:**
1. Line 1: Using :latest tag
   - Issue: `FROM node:latest`
   - Fix: `FROM node:20-bullseye`
   - Impact: Unpredictable builds, security risk

**HIGH:**
2. Line 45: Package cache not cleaned
   - Issue: `RUN apt-get install -y curl`
   - Fix: Add `&& rm -rf /var/lib/apt/lists/*`
   - Impact: Larger image size

**MEDIUM:**
3. Line 15: Using ADD instead of COPY
   - Issue: `ADD app.tar.gz /app/`
   - Fix: `COPY app.tar.gz /app/` (or extract separately)
   - Impact: Less explicit behavior

## Docker Compose Analysis

### [Compose File Path]

#### Validation Results
❌ **FAILED**: Obsolete 'version' field present
⚠️  **WARNING**: 3 services using :latest tags
✅ **PASSED**: Custom networks defined
✅ **PASSED**: Named volumes configured

#### Modern Syntax Compliance
- **Version Field**: Present ❌ (MUST REMOVE)
- **Specific Tags**: 2 of 5 services ⚠️
- **Restart Policies**: All services ✅
- **Health Checks**: 3 of 5 services ⚠️

#### Issues Found

**CRITICAL:**
1. Obsolete 'version' field
   - Issue: `version: '3.8'`
   - Fix: Remove the entire line
   - Impact: Using deprecated syntax

**HIGH:**
2. Service 'web' uses :latest tag
   - Issue: `image: nginx:latest`
   - Fix: `image: nginx:1.24-alpine`
   - Impact: Unpredictable deployments

3. No restart policy on 'cache' service
   - Issue: Missing `restart:` directive
   - Fix: Add `restart: unless-stopped`
   - Impact: Service won't auto-recover

## Recommendations

### Immediate Actions (Critical)
1. Pin all Docker image versions (remove :latest)
2. Remove obsolete 'version' field from Compose files
3. Ensure all services run as non-root users
4. Clean package manager caches in all Dockerfiles

### High Priority (Before Production)
1. Implement health checks for all services
2. Add restart policies to all Compose services
3. Set up resource limits (memory, CPU)
4. Implement proper secrets management

### Medium Priority (Best Practices)
1. Use COPY instead of ADD unless extracting archives
2. Add labels for better organization
3. Implement logging drivers
4. Add metadata to images

### Low Priority (Optimizations)
1. Consider slimmer base images where possible
2. Optimize layer caching with better ordering
3. Add comprehensive comments
4. Implement .dockerignore files

## Next Steps

1. **Fix Critical Issues** (Estimated: 30 minutes)
   - Pin image versions
   - Remove version field from Compose
   - Add USER directives

2. **Address High Priority** (Estimated: 1-2 hours)
   - Add health checks
   - Configure restart policies
   - Set resource limits

3. **Re-validate** (Estimated: 10 minutes)
   - Run validation again after fixes
   - Ensure all critical issues resolved

4. **Set Up Automation** (Estimated: 1 hour)
   - Add pre-commit hooks
   - Integrate into CI/CD
   - Schedule regular security scans

## Validation Tools Recommendations

### Install Required Tools

Hadolint (Dockerfile linter)

brew install hadolint # macOS

or

wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64

DCLint (Docker Compose linter)

npm install -g docker-compose-linter

Trivy (Security scanner)

brew install aquasecurity/trivy/trivy

### Automated Validation Script
[Provide custom validation script based on project needs]

### CI/CD Integration
[Provide GitHub Actions / GitLab CI configuration]

Deliverables

At the end of validation, provide:

1. Comprehensive Validation Report

• Executive summary with overall status
• Detailed findings per file
• Issue classification (Critical → Low)
• Specific fixes for each issue
• Recommendations prioritized

2. Fixed Configuration Files (if requested)

• Corrected Dockerfiles
• Updated Compose files
• .hadolint.yaml configuration
• .dclintrc.json configuration

3. Validation Script (if requested)

• Custom bash script for automated validation
• Checks for project-specific requirements
• Color-coded output
• Exit codes for CI/CD

4. CI/CD Integration (if requested)

• GitHub Actions workflow
• GitLab CI configuration
• Pre-commit hooks
• Integration with existing pipeline

5. Documentation

• How to run validation locally
• Tool installation instructions
• Best practices guide
• Common issues and solutions

Validation Script Template

When user requests automated validation, create this script:

#!/bin/bash
# docker-validation.sh

set -e

# Color codes
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

ERRORS=0
WARNINGS=0

echo -e "${BLUE}╔══════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║   Docker Configuration Validator        ║${NC}"
echo -e "${BLUE}╚══════════════════════════════════════════╝${NC}"

# 1. Prerequisites check
echo -e "\n${BLUE}━━━ Checking Prerequisites ━━━${NC}"
command -v docker >/dev/null || { echo "❌ Docker not found"; exit 1; }
command -v hadolint >/dev/null || echo "⚠️  Hadolint not installed"

# 2. Dockerfile validation
echo -e "\n${BLUE}━━━ Validating Dockerfiles ━━━${NC}"
find . -name "Dockerfile*" -type f | while read df; do
    echo "Checking: $df"
    # [Validation logic here]
done

# 3. Multi-stage build check
echo -e "\n${BLUE}━━━ Checking Multi-Stage Builds ━━━${NC}"
# [Multi-stage validation logic]

# 4. Compose validation
echo -e "\n${BLUE}━━━ Validating Docker Compose ━━━${NC}"
find . -name "*compose*.yml" | while read cf; do
    # Check for obsolete version field
    if grep -q "^version:" "$cf"; then
        echo -e "${RED}❌ $cf: Obsolete version field${NC}"
        ERRORS=$((ERRORS + 1))
    fi

    # Validate syntax
    docker compose -f "$cf" config --quiet || ERRORS=$((ERRORS + 1))
done

# 5. Security checks
echo -e "\n${BLUE}━━━ Security Audit ━━━${NC}"
# [Security validation logic]

# Final report
echo -e "\n${BLUE}╔══════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║         Validation Summary               ║${NC}"
echo -e "${BLUE}╚══════════════════════════════════════════╝${NC}"

if [ $ERRORS -eq 0 ]; then
    echo -e "${GREEN}✅ All checks passed!${NC}"
    exit 0
else
    echo -e "${RED}❌ Found $ERRORS error(s), $WARNINGS warning(s)${NC}"
    exit 1
fi

CI/CD Integration Templates

GitHub Actions

name: Docker Validation

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint Dockerfiles
        uses: hadolint/hadolint-action@v3.1.0
        with:
          dockerfile: ./Dockerfile
          failure-threshold: error

      - name: Validate Compose files
        run: |
          for f in $(find . -name "*compose*.yml"); do
            docker compose -f "$f" config --quiet
          done

      - name: Check for obsolete version field
        run: |
          if grep -r "^version:" . --include="*compose*.yml"; then
            echo "ERROR: Found obsolete version field"
            exit 1
          fi

GitLab CI

stages:
  - validate

docker-validation:
  stage: validate
  image: hadolint/hadolint:latest-debian
  script:
    - find . -name "Dockerfile*" -exec hadolint {} \;
    - |
      for f in $(find . -name "*compose*.yml"); do
        if grep -q "^version:" "$f"; then
          echo "ERROR: Obsolete version field in $f"
          exit 1
        fi
      done

Communication Style

When conducting validation:

1. Be Thorough

• Check all aspects systematically
• Don't skip manual checks if tools unavailable
• Validate both syntax and best practices

2. Prioritize Clearly

• Critical issues first (security, functionality)
• High priority next (production readiness)
• Medium and low as improvements

3. Provide Specific Fixes

• Show exact line numbers
• Provide before/after code
• Explain why the fix is needed
• Include impact assessment

4. Educate

• Explain Docker best practices
• Reference official documentation
• Provide learning resources
• Share modern syntax requirements

5. Be Actionable

• Give step-by-step remediation
• Provide automation scripts
• Suggest CI/CD integration
• Estimate effort for fixes

Common Validation Patterns

Pattern 1: Quick Syntax Check

• Run Hadolint and DCLint
• Check for obsolete version field
• Validate with Docker Compose config
• Report critical syntax errors only

Pattern 2: Full Production Audit

• Complete Dockerfile validation
• Multi-stage build verification
• Security audit
• Compose best practices
• Generate comprehensive report
• Provide automation scripts

Pattern 3: Security-Focused Review

• User privilege checks
• Secret exposure scan
• Base image security
• Network exposure audit
• Security scanning integration

Pattern 4: Optimization Review

• Multi-stage build effectiveness
• Layer optimization
• Image size analysis
• Build time improvements
• Caching strategies

Key Rules to Enforce

Dockerfile Rules (Critical)

• ✅ No :latest tags (DL3006)
• ✅ Last USER not root (DL3002)
• ✅ Use absolute WORKDIR (DL3000)
• ✅ Pin package versions (DL3008, DL3013)
• ✅ Clean package cache (DL3009)

Docker Compose Rules (Critical)

• ✅ NO version field (obsolete since v2.27.0)
• ✅ No :latest tags
• ✅ Restart policies defined
• ✅ Health checks configured
• ✅ Named volumes for persistence

Multi-Stage Build Rules

• ✅ Minimum 2 stages
• ✅ Named stages with AS
• ✅ COPY --from for artifacts
• ✅ Minimal final base image
• ✅ No build tools in final stage

Security Rules (Critical)

• ✅ Run as non-root USER
• ✅ No secrets in images
• ✅ Minimal base images
• ✅ Regular security scans
• ✅ Least privilege principle

Reference Resources

When providing recommendations, reference:

• Docker Best Practices: Official Docker documentation
• Hadolint Rules: Complete rule reference
• Compose Specification: Latest Compose spec
• Security Standards: CIS Docker Benchmark
• Multi-Stage Builds: Official guide and examples

Remember: Docker validation is about ensuring reliable, secure, and efficient containerized applications. Always prioritize security and production readiness while maintaining developer experience.

Docker Configuration Validator

Version: 1.0.0 Category: Development Description: Comprehensive Docker and Docker Compose validation following best practices and security standards

Overview

The Docker Configuration Validator skill provides expert-level validation of Dockerfiles and Docker Compose files, ensuring your Docker configurations follow modern best practices, security standards, and syntax requirements. This skill automates the validation process, identifies issues, and provides specific, actionable fixes.

Features

Dockerfile Validation

• ✅ Syntax Validation: Hadolint integration for deep Dockerfile analysis
• ✅ Multi-Stage Build Verification: Ensures proper multi-stage implementation
• ✅ Security Audit: Checks for root users, exposed secrets, vulnerable images
• ✅ Best Practices: Enforces Docker best practices and optimization patterns
• ✅ Layer Optimization: Identifies inefficient layer structure

Docker Compose Validation

• ✅ Modern Syntax Compliance: Ensures no obsolete version field (Compose v2.27.0+)
• ✅ Image Tag Validation: Checks for :latest tags and unpinned versions
• ✅ Service Configuration: Validates restart policies, health checks, resource limits
• ✅ Network & Volume Best Practices: Ensures proper networking and persistence
• ✅ Security Review: Checks for hardcoded secrets, privilege escalation

Automation & Integration

• ✅ Validation Scripts: Generates custom bash scripts for automated validation
• ✅ CI/CD Integration: Provides GitHub Actions and GitLab CI configurations
• ✅ Pre-commit Hooks: Creates hooks for local validation before commits
• ✅ Comprehensive Reports: Detailed validation reports with prioritized issues

When to Use This Skill

Use this skill when you need to:

• Validate Dockerfiles before committing to version control
• Review Docker configurations for production readiness
• Audit Docker security and identify vulnerabilities
• Ensure compliance with Docker best practices
• Modernize Docker Compose files (remove obsolete syntax)
• Create automated validation workflows
• Set up CI/CD pipeline validation
• Generate validation reports for team review
• Fix Docker configuration issues

How It Works

1. Initial Assessment

The skill starts by understanding what you need validated:

• Which files to check (Dockerfile, Compose, or both)
• Specific concerns or focus areas
• Whether automation is needed

2. Comprehensive Validation

Performs multi-layered validation:

• Syntax validation using Hadolint and DCLint (if available)
• Manual validation covering all critical best practices
• Security audit for vulnerabilities and misconfigurations
• Multi-stage build analysis for optimization opportunities
• Modern syntax compliance (especially for Compose files)

3. Issue Classification

Categorizes findings by severity:

• CRITICAL: Must fix before deployment (security, functionality)
• HIGH: Should fix before production (reliability, best practices)
• MEDIUM: Recommended improvements (optimization, maintainability)
• LOW: Nice-to-have enhancements (polish, edge cases)

4. Detailed Reporting

Generates comprehensive reports including:

• Executive summary with overall status
• Specific issues with line numbers
• Before/after code examples
• Impact assessment for each issue
• Prioritized recommendations
• Effort estimates for fixes

5. Automation (Optional)

Can create:

• Custom validation scripts
• CI/CD pipeline configurations
• Pre-commit hooks
• Regular security scan setups

Prerequisites

Required

• Docker: Validation needs Docker CLI for syntax checking

  docker --version  # Should be 20.10+
  docker compose version  # Should be v2.27.0+

Recommended

• Hadolint: Dockerfile linter (highly recommended)

  # macOS
  brew install hadolint

  # Linux
  wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64
  chmod +x /usr/local/bin/hadolint

  # Verify
  hadolint --version

• DCLint: Docker Compose linter (recommended)

  # Install via npm
  npm install -g docker-compose-linter

  # Verify
  dclint --version

Note: The skill can perform validation even without these tools, but they significantly enhance the validation quality.

Example Usage

Basic Validation

User: "Can you validate my Dockerfile?"

Claude: "I'll validate your Dockerfile for best practices and security. Let me check..."

[Claude performs comprehensive validation and provides detailed report]

Docker Compose Modernization

User: "Check my docker-compose.yml for issues"

Claude: "I'll validate your Docker Compose file. Checking for modern syntax compliance..."

[Claude identifies obsolete version field and other issues]

"❌ CRITICAL: Found obsolete 'version' field. This is deprecated in Compose v2.27.0+.
Remove the 'version: 3.8' line from your compose file."

Full Project Audit

User: "Audit all Docker configs in my project for production readiness"

Claude: "I'll perform a comprehensive audit of all Dockerfiles and Compose files..."

[Claude validates all files and generates full security and best practices report]

Automation Setup

User: "Create a validation script I can run in CI/CD"

Claude: "I'll create a comprehensive validation script with CI/CD integration..."

[Claude generates bash script + GitHub Actions workflow]

Key Validation Checks

Dockerfile Checks

• ❌ No :latest tags → Pin specific versions
• ❌ Running as root → Use non-root USER
• ❌ Single-stage build → Implement multi-stage
• ❌ Using ADD → Prefer COPY unless extracting
• ❌ No HEALTHCHECK → Add health monitoring
• ❌ No cache cleanup → Clean package manager caches
• ❌ Relative WORKDIR → Use absolute paths

Docker Compose Checks

• ❌ version: field present → REMOVE (obsolete)
• ❌ :latest tags → Pin specific versions
• ❌ No restart policy → Add restart directives
• ❌ No health checks → Configure health monitoring
• ❌ No named volumes → Use named volumes for persistence
• ❌ No custom networks → Define custom networks
• ❌ Hardcoded secrets → Use environment variables or secrets management

Security Checks

• ❌ Running as root user
• ❌ Secrets in image layers
• ❌ Unnecessary privileges
• ❌ Vulnerable base images
• ❌ Excessive port exposure
• ❌ Missing security updates

Validation Report Example

# Docker Configuration Validation Report

## Executive Summary
- Total Dockerfiles: 3
- Total Compose Files: 1
- Critical Issues: 2
- High Priority: 4
- Status: ⚠️ REQUIRES FIXES

## Critical Issues
1. Dockerfile (line 1): Using :latest tag
   Fix: FROM node:20-bullseye
   Impact: Unpredictable builds

2. docker-compose.yml (line 1): Obsolete version field
   Fix: Remove 'version: 3.8' line
   Impact: Using deprecated syntax

## Recommendations
- Immediate: Pin all image versions, remove version field
- High Priority: Add health checks, configure restart policies
- Medium: Implement multi-stage builds for optimization

Common Issues & Fixes

Issue: Obsolete Docker Compose Version Field

Problem:

version: '3.8'  # ❌ Obsolete!
services:
  web:
    image: nginx

Fix:

# No version field needed!
services:
  web:
    image: nginx:1.24-alpine

Issue: Running as Root

Problem:

FROM alpine
COPY app /app
CMD ["/app/server"]  # Runs as root!

Fix:

FROM alpine
RUN addgroup -g 1001 appuser && \
    adduser -D -u 1001 -G appuser appuser
COPY --chown=appuser:appuser app /app
USER appuser
CMD ["/app/server"]

Issue: No Multi-Stage Build

Problem:

FROM node:18
COPY . .
RUN npm install  # Includes dev dependencies!
CMD ["npm", "start"]

Fix:

# Build stage
FROM node:18 AS builder
COPY . .
RUN npm ci && npm run build

# Runtime stage
FROM node:18-alpine
COPY --from=builder /app/dist ./dist
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

Best Practices Enforced

Dockerfile Best Practices

• Use specific image tags (no :latest)
• Implement multi-stage builds
• Run as non-root user
• Use COPY instead of ADD
• Add HEALTHCHECK instructions
• Clean package manager caches
• Use absolute WORKDIR paths
• Add appropriate labels

Docker Compose Best Practices

• No version field (obsolete in v2.27.0+)
• Pin all image versions
• Define restart policies
• Configure health checks
• Use named volumes
• Define custom networks
• Manage secrets properly
• Set resource limits

Security Best Practices

• Never run as root
• No secrets in images
• Use minimal base images
• Regular security scans
• Least privilege principle
• Network isolation
• Read-only root filesystem (where applicable)

Integration Examples

GitHub Actions

name: Docker Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hadolint/hadolint-action@v3.1.0
        with:
          dockerfile: Dockerfile
      - run: docker compose config --quiet

GitLab CI

docker-validation:
  stage: validate
  image: hadolint/hadolint:latest
  script:
    - hadolint Dockerfile
    - docker compose config --quiet

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -q "Dockerfile"; then
    hadolint Dockerfile || exit 1
fi

Resources

Validation Tools

• Hadolint - Dockerfile linter
• DCLint - Compose linter
• Trivy - Security scanner

Documentation

• Docker Best Practices
• Dockerfile Reference
• Compose Specification
• Hadolint Rules

Learning Resources

• Multi-Stage Builds Guide
• Security Best Practices
• Compose v2 Migration

Support

For issues with this skill or suggestions for improvements:

• Check the skill's SKILL.md for detailed workflow
• Review validation-checklist.md for complete rule set
• Consult tool-installation.md for setup help

Version History

1.0.0 (2025-10-18)

• Initial release
• Comprehensive Dockerfile validation
• Docker Compose validation with modern syntax checking
• Multi-stage build verification
• Security audit capabilities
• Automation script generation
• CI/CD integration templates

---

Maintainer: rknall Last Updated: 2025-10-18 Skill Type: Development / DevOps

Docker Validation Tools Installation Guide

Complete installation instructions for all tools needed for Docker configuration validation.

Required Tools

1. Docker & Docker Compose

macOS

# Install Docker Desktop (includes Docker and Compose)
brew install --cask docker

# Start Docker Desktop application
open -a Docker

# Verify installation
docker --version
docker compose version

Linux (Ubuntu/Debian)

# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify installation
docker --version
docker compose version

Windows

# Install Docker Desktop via Chocolatey
choco install docker-desktop

# Or download from https://www.docker.com/products/docker-desktop

# Verify installation
docker --version
docker compose version

Minimum Versions:

• Docker: 20.10.0+
• Docker Compose: v2.27.0+ (for modern syntax support)

Validation Tools

2. Hadolint (Dockerfile Linter)

Why Hadolint?

• Parses Dockerfile into AST for deep analysis
• Integrates ShellCheck for bash validation
• Enforces Docker best practices
• Highly configurable

macOS

# Install via Homebrew (recommended)
brew install hadolint

# Verify installation
hadolint --version

Linux

# Download binary (x86_64)
HADOLINT_VERSION=v2.12.0
wget -O /usr/local/bin/hadolint \
  https://github.com/hadolint/hadolint/releases/download/${HADOLINT_VERSION}/hadolint-Linux-x86_64

# Make executable
chmod +x /usr/local/bin/hadolint

# Verify installation
hadolint --version

Windows

# Download binary
$HADOLINT_VERSION = "v2.12.0"
Invoke-WebRequest -Uri "https://github.com/hadolint/hadolint/releases/download/${HADOLINT_VERSION}/hadolint-Windows-x86_64.exe" -OutFile "hadolint.exe"

# Move to PATH location
Move-Item hadolint.exe C:\Windows\System32\hadolint.exe

# Verify installation
hadolint --version

Using Docker (Cross-platform)

# Run Hadolint in container
docker run --rm -i hadolint/hadolint:latest < Dockerfile

# Create alias for convenience
echo 'alias hadolint="docker run --rm -i hadolint/hadolint:latest"' >> ~/.bashrc
source ~/.bashrc

# Verify
hadolint --version

VS Code Integration

# Install VS Code extension
code --install-extension exiasr.hadolint

# Extension will automatically use hadolint if installed

3. DCLint (Docker Compose Linter)

Why DCLint?

• Validates Docker Compose syntax
• Enforces best practices
• Checks for obsolete version field
• Auto-fix capabilities

Prerequisites

# Requires Node.js 20.19.0+
node --version

# If not installed:
# macOS
brew install node

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
choco install nodejs

Installation

# Install globally via npm (recommended)
npm install -g docker-compose-linter

# Or install locally in project
npm install --save-dev docker-compose-linter

# Verify installation
dclint --version

Using npx (No Installation)

# Run without global install
npx dclint docker-compose.yml

4. Trivy (Security Scanner)

Why Trivy?

• Comprehensive vulnerability scanner
• Scans images, filesystems, and configs
• Free and open-source
• Fast and easy to use

macOS

# Install via Homebrew
brew install aquasecurity/trivy/trivy

# Verify installation
trivy --version

Linux (Debian/Ubuntu)

# Add repository
sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list

# Install
sudo apt-get update
sudo apt-get install trivy

# Verify installation
trivy --version

Using Docker

# Run Trivy in container
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy:latest image nginx:latest

# Scan Dockerfile
docker run --rm -v $(pwd):/app aquasec/trivy:latest config /app/Dockerfile

Optional But Recommended Tools

5. Dive (Image Layer Analyzer)

Analyzes Docker image layers to optimize size.

# macOS
brew install dive

# Linux
wget https://github.com/wagoodman/dive/releases/download/v0.11.0/dive_0.11.0_linux_amd64.deb
sudo apt install ./dive_0.11.0_linux_amd64.deb

# Usage
dive nginx:latest

6. Docker Bench Security

Automated security audit for Docker deployments.

# Run security audit
docker run --rm --net host --pid host --userns host --cap-add audit_control \
    -e DOCKER_CONTENT_TRUST=$DOCKER_CONTENT_TRUST \
    -v /etc:/etc:ro \
    -v /usr/bin/containerd:/usr/bin/containerd:ro \
    -v /usr/bin/runc:/usr/bin/runc:ro \
    -v /usr/lib/systemd:/usr/lib/systemd:ro \
    -v /var/lib:/var/lib:ro \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    --label docker_bench_security \
    docker/docker-bench-security

7. Snyk (Alternative Security Scanner)

# Install Snyk CLI
npm install -g snyk

# Authenticate
snyk auth

# Test Dockerfile
snyk container test nginx:latest

# Test Docker image
snyk container test myapp:latest --file=Dockerfile

Configuration Files Setup

Create .hadolint.yaml

cat > .hadolint.yaml << 'EOF'
---
ignored:
  - DL3008  # Pin versions in apt-get (sometimes too strict)
  - DL3013  # Pin versions in pip
  - DL3018  # Pin versions in apk

override:
  error:
    - DL3002  # Last user should not be root
    - DL3020  # Use COPY instead of ADD
  warning:
    - DL3003  # Use WORKDIR instead of cd

trustedRegistries:
  - docker.io
  - ghcr.io
  - gcr.io
  - quay.io

strict-labels: true
EOF

Create .dclintrc.json

cat > .dclintrc.json << 'EOF'
{
  "rules": {
    "no-version-field": "error",
    "require-quotes": "warning",
    "service-name-case": ["error", "kebab-case"],
    "no-duplicate-keys": "error",
    "require-restart": "warning"
  },
  "exclude": [
    "node_modules/**",
    ".git/**",
    "dist/**"
  ]
}
EOF

Create .dockerignore

cat > .dockerignore << 'EOF'
# Git
.git
.gitignore
.gitattributes

# CI/CD
.github
.gitlab-ci.yml
Jenkinsfile

# Documentation
README.md
CHANGELOG.md
docs/

# Dependencies
node_modules/
vendor/
__pycache__/
*.pyc

# Build artifacts
dist/
build/
target/
*.log

# IDE
.vscode/
.idea/
*.swp
*.swo

# Environment
.env
.env.local
*.pem
*.key
EOF

Verification Script

Create a script to verify all tools are installed:

#!/bin/bash
# verify-tools.sh

echo "🔍 Checking Docker Validation Tools..."
echo ""

# Check Docker
if command -v docker &> /dev/null; then
    echo "✅ Docker: $(docker --version)"
else
    echo "❌ Docker: NOT INSTALLED"
fi

# Check Docker Compose
if docker compose version &> /dev/null; then
    echo "✅ Docker Compose: $(docker compose version)"
else
    echo "❌ Docker Compose: NOT INSTALLED"
fi

# Check Hadolint
if command -v hadolint &> /dev/null; then
    echo "✅ Hadolint: $(hadolint --version)"
else
    echo "⚠️  Hadolint: NOT INSTALLED (recommended)"
fi

# Check DCLint
if command -v dclint &> /dev/null; then
    echo "✅ DCLint: $(dclint --version 2>&1 | head -1)"
else
    echo "⚠️  DCLint: NOT INSTALLED (recommended)"
fi

# Check Trivy
if command -v trivy &> /dev/null; then
    echo "✅ Trivy: $(trivy --version | head -1)"
else
    echo "⚠️  Trivy: NOT INSTALLED (optional)"
fi

# Check Node.js (for DCLint)
if command -v node &> /dev/null; then
    echo "✅ Node.js: $(node --version)"
else
    echo "⚠️  Node.js: NOT INSTALLED (needed for DCLint)"
fi

echo ""
echo "📊 Installation Summary:"
echo "   Required tools: Docker, Docker Compose"
echo "   Recommended: Hadolint, DCLint"
echo "   Optional: Trivy, Dive, Docker Bench"

Make it executable and run:

chmod +x verify-tools.sh
./verify-tools.sh

Quick Start Commands

After installation, test the tools:

# Test Hadolint
echo 'FROM node:latest' > test.Dockerfile
hadolint test.Dockerfile
rm test.Dockerfile

# Test DCLint
echo 'services:
  web:
    image: nginx:latest' > test-compose.yml
dclint test-compose.yml
rm test-compose.yml

# Test Docker Compose validation
docker compose config --quiet

# Test Trivy (if installed)
trivy image nginx:latest

# Test full validation
./validate-docker.sh  # (if you have the validation script)

Troubleshooting

Hadolint: Command not found

# Check if binary exists
ls -la /usr/local/bin/hadolint

# Check PATH
echo $PATH

# Add to PATH if needed
export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

DCLint: Module not found

# Check npm global prefix
npm config get prefix

# If not in PATH, add it
export PATH="$(npm config get prefix)/bin:$PATH"

# Or use npx
npx dclint docker-compose.yml

Docker Compose: version command not recognized

# Check Docker Compose version
docker compose version  # New (v2)
docker-compose --version  # Old (v1, deprecated)

# If using v1, upgrade to v2
# Follow Docker documentation for your OS

Permission Denied (Linux)

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker ps

CI/CD Integration

GitHub Actions

Already includes all tools in standard ubuntu-latest runner:

- name: Validate Docker configs
  run: |
    docker --version
    docker compose version
    # Install additional tools if needed

GitLab CI

before_script:
  - apt-get update
  - apt-get install -y wget
  - wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64
  - chmod +x /usr/local/bin/hadolint

Update Tools

Keep tools up to date:

# Update Hadolint (macOS)
brew upgrade hadolint

# Update DCLint
npm update -g docker-compose-linter

# Update Trivy (macOS)
brew upgrade trivy

# Update Docker Desktop
# Use built-in updater or:
brew upgrade --cask docker

---

All tools installed? Run `./verify-tools.sh` to confirm!

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

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

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.