# Docker Validation Tools Installation Guide

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

## Required Tools

### 1. Docker & Docker Compose

#### macOS
```bash
# 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)
```bash
# 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
```powershell
# 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
```bash
# Install via Homebrew (recommended)
brew install hadolint

# Verify installation
hadolint --version
```

#### Linux
```bash
# 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
```powershell
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# Install via Homebrew
brew install aquasecurity/trivy/trivy

# Verify installation
trivy --version
```

#### Linux (Debian/Ubuntu)
```bash
# 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
```bash
# 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.

```bash
# 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.

```bash
# 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)

```bash
# 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
```bash
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
```bash
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
```bash
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:

```bash
#!/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:
```bash
chmod +x verify-tools.sh
./verify-tools.sh
```

## Quick Start Commands

After installation, test the tools:

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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:
```yaml
- name: Validate Docker configs
  run: |
    docker --version
    docker compose version
    # Install additional tools if needed
```

### GitLab CI
```yaml
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:

```bash
# 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!**