gh-rknall-claude-skills-docker-validation/tool-installation.md

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!