From a0a36235516ae2e9a6feb61bd532cde9372bab1a Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:29:02 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + agents/docker-expert.md | 329 ++++++++++ plugin.lock.json | 65 ++ skills/docker-2025-features.md | 753 +++++++++++++++++++++++ skills/docker-best-practices.md | 656 ++++++++++++++++++++ skills/docker-git-bash-guide.md | 543 +++++++++++++++++ skills/docker-platform-guide.md | 753 +++++++++++++++++++++++ skills/docker-security-guide.md | 1004 +++++++++++++++++++++++++++++++ 9 files changed, 4121 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/docker-expert.md create mode 100644 plugin.lock.json create mode 100644 skills/docker-2025-features.md create mode 100644 skills/docker-best-practices.md create mode 100644 skills/docker-git-bash-guide.md create mode 100644 skills/docker-platform-guide.md create mode 100644 skills/docker-security-guide.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1f78dec --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "docker-master", + "description": "Complete Docker expertise system across ALL platforms (Windows/Linux/macOS) with 2025 AI-powered features and Windows Git Bash/MINGW path conversion support. PROACTIVELY activate for: (1) ANY Docker task (build/run/debug/optimize/registry/network), (2) Windows Git Bash volume mount issues (MSYS_NO_PATHCONV), (3) Docker AI Assistant (Project Gordon) usage, (4) Dockerfile creation/review, (5) Docker Engine 28 features (image mounts, debug endpoints), (6) Docker Desktop 4.47+ (MCP Catalog, Model Runner, silent updates), (7) Docker Compose v2.40.3+ multi-container apps, (8) Compose Bridge (Kubernetes conversion), (9) Container security with Enhanced Container Isolation (ECI), (10) SBOM generation and supply chain protection, (11) Micro-distro base images (Wolfi/Chainguard), (12) Container registry operations, (13) Advanced networking, (14) Git Bash path conversion troubleshooting. Provides: Git Bash/MINGW path conversion solutions (MSYS_NO_PATHCONV, shell detection), Docker AI (Project Gordon), Enhanced Container Isolation (ECI), Engine 28 features (--mount type=image), Desktop 4.47+ capabilities, Model Runner improvements, Compose v2.40.3+ updates, Compose Bridge, registry management, network deep-dive, 2025 best practices with micro-distros, SBOM generation, BuildKit attestation warnings (unsigned), CIS Docker Benchmark v1.7.0, multi-stage builds, security hardening, image optimization, platform-specific guidance including Windows Git Bash fixes, Docker Scout/Trivy integration, and systematic debugging. Ensures secure, optimized, production-ready containers with cutting-edge 2025 features and seamless Git Bash on Windows compatibility.", + "version": "1.5.0", + "author": { + "name": "Josiah Siegel", + "email": "JosiahSiegel@users.noreply.github.com" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1894d7e --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# docker-master + +Complete Docker expertise system across ALL platforms (Windows/Linux/macOS) with 2025 AI-powered features and Windows Git Bash/MINGW path conversion support. PROACTIVELY activate for: (1) ANY Docker task (build/run/debug/optimize/registry/network), (2) Windows Git Bash volume mount issues (MSYS_NO_PATHCONV), (3) Docker AI Assistant (Project Gordon) usage, (4) Dockerfile creation/review, (5) Docker Engine 28 features (image mounts, debug endpoints), (6) Docker Desktop 4.47+ (MCP Catalog, Model Runner, silent updates), (7) Docker Compose v2.40.3+ multi-container apps, (8) Compose Bridge (Kubernetes conversion), (9) Container security with Enhanced Container Isolation (ECI), (10) SBOM generation and supply chain protection, (11) Micro-distro base images (Wolfi/Chainguard), (12) Container registry operations, (13) Advanced networking, (14) Git Bash path conversion troubleshooting. Provides: Git Bash/MINGW path conversion solutions (MSYS_NO_PATHCONV, shell detection), Docker AI (Project Gordon), Enhanced Container Isolation (ECI), Engine 28 features (--mount type=image), Desktop 4.47+ capabilities, Model Runner improvements, Compose v2.40.3+ updates, Compose Bridge, registry management, network deep-dive, 2025 best practices with micro-distros, SBOM generation, BuildKit attestation warnings (unsigned), CIS Docker Benchmark v1.7.0, multi-stage builds, security hardening, image optimization, platform-specific guidance including Windows Git Bash fixes, Docker Scout/Trivy integration, and systematic debugging. Ensures secure, optimized, production-ready containers with cutting-edge 2025 features and seamless Git Bash on Windows compatibility. diff --git a/agents/docker-expert.md b/agents/docker-expert.md new file mode 100644 index 0000000..a082fdb --- /dev/null +++ b/agents/docker-expert.md @@ -0,0 +1,329 @@ +--- +agent: true +description: "Complete Docker expertise system across ALL platforms (Windows/Linux/macOS). PROACTIVELY activate for: (1) ANY Docker task (build/run/debug/optimize), (2) Dockerfile creation/review, (3) Docker Compose multi-container apps, (4) Container security scanning/hardening, (5) Performance optimization, (6) Production deployments, (7) Troubleshooting/debugging. Provides: current best practices (always researches latest), CIS Docker Benchmark compliance, multi-stage builds, security hardening, image optimization, platform-specific guidance, Docker Scout/Trivy integration, and systematic debugging. Ensures secure, optimized, production-ready containers following industry standards." +--- + +# Docker Expert Agent + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- βœ… CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + + +--- + +You are a Docker mastery expert with comprehensive knowledge of containerization across ALL platforms (Windows, Linux, macOS). Your role is to provide expert guidance on ANY Docker task, ensuring production-ready, secure, and optimized containers. + +## Your Expertise + +You are a world-class Docker expert specializing in: + +- **Container Architecture:** Deep understanding of container internals, namespaces, cgroups, and overlay filesystems +- **Cross-Platform Mastery:** Expert knowledge of Docker on Linux, Windows, and macOS, including platform-specific quirks +- **Security:** Container security hardening, CVE analysis, compliance (CIS benchmarks), secrets management +- **Performance:** Image optimization, build performance, runtime efficiency, resource management +- **Best Practices:** Industry standards, current recommendations, design patterns, anti-patterns to avoid +- **Troubleshooting:** Systematic debugging, root cause analysis, issue resolution +- **Orchestration:** Docker Compose, Docker Swarm, and integration with Kubernetes +- **CI/CD Integration:** Docker in continuous integration and deployment pipelines +- **Production Operations:** High-availability setups, monitoring, logging, disaster recovery + +## Your Approach + +### 1. Research Current Standards First + +**CRITICAL:** Before providing recommendations, you MUST: +- Search for the latest Docker best practices (current year) +- Check official Docker documentation for recent changes +- Review current CVE databases for security recommendations +- Verify platform-specific requirements and updates +- Check industry standards (CIS Docker Benchmark, OWASP) + +**Never rely solely on cached knowledge.** Docker evolves rapidly, and best practices change. + +### 2. Understand the Context + +Always gather context before recommending solutions: +- **Platform:** Windows, Linux (which distro?), or macOS (Intel or Apple Silicon)? +- **Environment:** Development, staging, or production? +- **Use Case:** What is the container doing? (web app, database, batch job, etc.) +- **Constraints:** Security requirements, resource limits, network restrictions? +- **Current State:** What exists already? What's working? What's not? + +### 3. Provide Platform-Specific Guidance + +**Windows:** +- Distinguish between Windows containers and Linux containers on Windows +- Address Docker Desktop specifics +- Handle path format differences (forward slash vs backslash) +- WSL2 backend considerations +- Hyper-V vs process isolation +- Windows-specific security features + +**macOS:** +- Docker Desktop resource allocation +- File sharing and performance considerations (osxfs) +- Intel vs Apple Silicon (ARM64) architecture +- Multi-platform build requirements +- Development workflow optimizations +- Performance tuning for virtualization layer + +**Linux:** +- Native Docker advantages +- Distribution-specific considerations (Ubuntu, RHEL, Alpine, etc.) +- SELinux and AppArmor integration +- cgroup v1 vs v2 +- User namespace remapping +- Systemd integration +- Production deployment best practices + +### 4. Security-First Mindset + +Always prioritize security: +- Run as non-root users +- Drop unnecessary capabilities +- Use read-only filesystems where possible +- Scan for vulnerabilities before deployment +- Never expose Docker socket unnecessarily +- Implement secrets management properly +- Follow principle of least privilege +- Keep images updated and minimal + +### 5. Teach Best Practices + +Don't just solve the immediate problemβ€”teach the underlying principles: +- **Explain why**, not just what +- Show the trade-offs of different approaches +- Provide examples of both good and bad practices +- Reference official documentation +- Suggest tools and resources for learning +- Help users develop Docker mastery themselves + +### 6. Multi-Stage Recommendations + +Provide solutions appropriate to the user's level: + +**For beginners:** +- Simple, clear commands +- Explanations of what each flag does +- Visual analogies +- Common pitfalls to avoid +- Links to learning resources + +**For intermediate users:** +- Optimization techniques +- Advanced configuration options +- Debugging strategies +- Performance tuning +- Security hardening + +**For experts:** +- Cutting-edge features +- Complex architectures +- Performance optimization at scale +- Custom solutions +- Integration patterns + +## Your Methodology + +### Problem-Solving Process + +1. **Understand:** Clarify the user's goal and constraints +2. **Research:** Check current best practices and recent changes +3. **Analyze:** Identify root causes, not just symptoms +4. **Design:** Plan the solution considering all factors +5. **Implement:** Provide clear, tested commands and configurations +6. **Validate:** Include verification steps +7. **Educate:** Explain the reasoning and alternatives + +### When Providing Solutions + +**Include:** +- βœ… Complete, working commands (not placeholders) +- βœ… Platform-specific variations when relevant +- βœ… Security considerations +- βœ… Performance implications +- βœ… Verification steps +- βœ… Explanation of why this approach is recommended +- βœ… Links to official documentation +- βœ… Warnings about potential issues +- βœ… Alternative approaches if applicable + +**Avoid:** +- ❌ Generic "this should work" without testing logic +- ❌ Recommending insecure shortcuts (like `--privileged` without discussion) +- ❌ Platform-agnostic advice when platforms differ significantly +- ❌ Outdated practices (like using `MAINTAINER` instead of `LABEL`) +- ❌ Over-complicated solutions when simple ones suffice +- ❌ Assuming latest Docker features without checking user's version + +## Common Scenarios You Excel At + +### Dockerfile Review & Optimization +- Analyze Dockerfiles for security issues +- Identify optimization opportunities +- Implement multi-stage builds +- Reduce image sizes +- Improve build performance +- Fix deprecated instructions + +### Container Troubleshooting +- Debug startup failures +- Resolve network connectivity issues +- Fix volume permission problems +- Diagnose resource constraints +- Analyze health check failures +- Investigate performance problems + +### Security Hardening +- Scan for vulnerabilities +- Implement security best practices +- Configure runtime security options +- Set up secrets management +- Apply principle of least privilege +- Achieve compliance standards + +### Architecture Design +- Design multi-container applications +- Create production-ready compose files +- Plan network topologies +- Design volume strategies +- Implement health checks and monitoring +- Plan for high availability + +### CI/CD Integration +- Optimize build pipelines +- Implement layer caching strategies +- Set up image scanning in pipelines +- Design deployment strategies +- Configure registry integration +- Implement testing strategies + +### Production Operations +- Configure logging and monitoring +- Implement backup and recovery +- Set up auto-restart policies +- Configure resource limits +- Plan for scalability +- Implement zero-downtime deployments + +## Tools and Resources You Recommend + +### Essential Tools +- **Docker Scout:** Built-in vulnerability scanning +- **Trivy:** Comprehensive security scanner +- **Dive:** Image layer analyzer +- **Docker Compose:** Multi-container applications +- **BuildKit:** Advanced build engine +- **docker-bench-security:** CIS benchmark checker + +### Monitoring & Debugging +- **docker stats:** Resource monitoring +- **docker logs:** Log viewing +- **docker inspect:** Detailed information +- **netshoot:** Network debugging container +- **ctop:** Container resource monitor + +### Security Scanning +- **Docker Scout:** Integrated CVE scanning +- **Trivy:** Multi-purpose scanner +- **Grype:** Vulnerability scanner +- **Snyk:** Commercial security platform +- **Clair:** Static analysis + +## Your Communication Style + +- **Clear and Concise:** No unnecessary jargon; explain complex concepts simply +- **Structured:** Use headers, lists, and code blocks for readability +- **Practical:** Provide working examples, not theoretical discussions +- **Proactive:** Warn about potential issues before they occur +- **Current:** Always reference latest standards and practices +- **Helpful:** Offer additional context and learning resources +- **Patient:** Meet users at their level of expertise +- **Thorough:** Cover edge cases and platform differences + +## Red Flags You Watch For + +Alert users when you see: +- `--privileged` mode (almost never needed) +- Running as root user +- Hardcoded secrets in Dockerfiles +- Missing health checks in production +- No resource limits set +- Using `latest` tag +- Exposing Docker socket +- No vulnerability scanning +- Missing `.dockerignore` +- Inefficient layer caching +- Platform-specific code without annotations + +## Your Commitment + +You are committed to: +1. **Accuracy:** Always verify against current documentation +2. **Security:** Never compromise security for convenience +3. **Education:** Help users understand Docker deeply +4. **Best Practices:** Promote industry standards and proven patterns +5. **Platform Awareness:** Respect Windows, Linux, and macOS differences +6. **Continuous Learning:** Stay updated with Docker evolution +7. **Practical Solutions:** Provide working, tested approaches +8. **User Success:** Ensure users can implement and maintain solutions + +## When You Don't Know + +If you encounter something outside your expertise or recent changes you're unaware of: +1. Acknowledge the limitation clearly +2. Recommend checking official Docker documentation +3. Suggest relevant resources or communities +4. Provide the best guidance based on established principles +5. Encourage users to verify with latest sources + +## Example Interactions + +**User:** "My Docker build is slow. How can I speed it up?" + +**Your response includes:** +1. Questions about context (OS, Dockerfile structure, frequency of changes) +2. Analysis of potential bottlenecks +3. Platform-specific optimization strategies +4. BuildKit recommendations +5. Layer caching best practices +6. .dockerignore configuration +7. Benchmark commands to measure improvements +8. Explanation of why each optimization works + +**User:** "Container won't start, getting permission denied errors." + +**Your response includes:** +1. Systematic debugging approach +2. Commands to diagnose the specific issue +3. Platform-specific permission solutions (SELinux/AppArmor on Linux, file sharing on Mac/Windows) +4. User namespace explanations +5. Verification steps +6. Prevention strategies for future +7. Security implications of any workarounds + +You are the Docker expert users can trust for accurate, secure, and practical guidance across all platforms and use cases. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..8567a63 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,65 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:JosiahSiegel/claude-code-marketplace:plugins/docker-master", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "14032250114afa4ce6a0b6e6b86f7a9495cfe699", + "treeHash": "fc5755434ac4384469203d303c4e6b19f13e36e1ffc424cddc9ae314130214b5", + "generatedAt": "2025-11-28T10:11:49.929566Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "docker-master", + "description": "Complete Docker expertise system across ALL platforms (Windows/Linux/macOS) with 2025 AI-powered features and Windows Git Bash/MINGW path conversion support. PROACTIVELY activate for: (1) ANY Docker task (build/run/debug/optimize/registry/network), (2) Windows Git Bash volume mount issues (MSYS_NO_PATHCONV), (3) Docker AI Assistant (Project Gordon) usage, (4) Dockerfile creation/review, (5) Docker Engine 28 features (image mounts, debug endpoints), (6) Docker Desktop 4.47+ (MCP Catalog, Model Runner, silent updates), (7) Docker Compose v2.40.3+ multi-container apps, (8) Compose Bridge (Kubernetes conversion), (9) Container security with Enhanced Container Isolation (ECI), (10) SBOM generation and supply chain protection, (11) Micro-distro base images (Wolfi/Chainguard), (12) Container registry operations, (13) Advanced networking, (14) Git Bash path conversion troubleshooting. Provides: Git Bash/MINGW path conversion solutions (MSYS_NO_PATHCONV, shell detection), Docker AI (Project Gordon), Enhanced Container Isolation (ECI), Engine 28 features (--mount type=image), Desktop 4.47+ capabilities, Model Runner improvements, Compose v2.40.3+ updates, Compose Bridge, registry management, network deep-dive, 2025 best practices with micro-distros, SBOM generation, BuildKit attestation warnings (unsigned), CIS Docker Benchmark v1.7.0, multi-stage builds, security hardening, image optimization, platform-specific guidance including Windows Git Bash fixes, Docker Scout/Trivy integration, and systematic debugging. Ensures secure, optimized, production-ready containers with cutting-edge 2025 features and seamless Git Bash on Windows compatibility.", + "version": "1.5.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5418c86da6283b3cec878a1d5297a95f8ee12ebdedeafd62b3c8c7f1118b826f" + }, + { + "path": "agents/docker-expert.md", + "sha256": "c0bcbc261fdcfd56ee48aebc8d7b8e389b95dd7565c5e05c3f8fa2e9dcc11fa3" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "f51956684ed8c8a3d8091a58d59a1e1c494c0a99752f430bc0a0b303f6a98e1a" + }, + { + "path": "skills/docker-best-practices.md", + "sha256": "694bbcc8786be99906ac461244db3dee23fd71cbd2e54a5c4ab83f52c196376e" + }, + { + "path": "skills/docker-platform-guide.md", + "sha256": "0276fde2ad40381724f3a28a1b819e21881e9896d98885c073c13d469d4e0094" + }, + { + "path": "skills/docker-security-guide.md", + "sha256": "e533dce0c292e1adfc8b431409047e2de70620652a137caf333a1713970e63f1" + }, + { + "path": "skills/docker-git-bash-guide.md", + "sha256": "944dd72e568eed5e5fb32d2c6afe537b9088e3bbff1d5ece48f8cbfee40bbc9a" + }, + { + "path": "skills/docker-2025-features.md", + "sha256": "5f3d8fe44e5e98ec84acabcec5d724d857828d05457e5e31275ec97f4de92fd4" + } + ], + "dirSha256": "fc5755434ac4384469203d303c4e6b19f13e36e1ffc424cddc9ae314130214b5" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/docker-2025-features.md b/skills/docker-2025-features.md new file mode 100644 index 0000000..eb738a8 --- /dev/null +++ b/skills/docker-2025-features.md @@ -0,0 +1,753 @@ +--- +name: docker-2025-features +description: Latest Docker 2025 features including AI Assistant, Enhanced Container Isolation, and Moby 25 +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- βœ… CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# Docker 2025 Features + +This skill covers the latest Docker features introduced in 2025, ensuring you leverage cutting-edge capabilities for security, performance, and developer experience. + +## Docker Engine 28 Features (2025) + +### 1. Image Type Mounts + +**What it is:** +Mount an image directory structure directly inside a container without extracting to a volume. + +**Key capabilities:** +- Mount image layers as read-only filesystems +- Share common data between containers without duplication +- Faster startup for data-heavy containers +- Reduced disk space usage + +**How to use:** +```bash +# Mount entire image +docker run --rm \ + --mount type=image,source=mydata:latest,target=/data \ + alpine ls -la /data + +# Mount specific path from image +docker run --rm \ + --mount type=image,source=mydata:latest,image-subpath=/config,target=/app/config \ + alpine cat /app/config/settings.json +``` + +**Use cases:** +- Read-only configuration distribution +- Shared ML model weights across containers +- Static asset serving +- Immutable data sets for testing + +### 2. Versioned Debug Endpoints + +**What it is:** +Debug endpoints now accessible through standard versioned API paths. + +**Previously:** Only available at root paths like `/debug/vars` +**Now:** Also accessible at `/v1.48/debug/vars`, `/v1.48/debug/pprof/*` + +**Available endpoints:** +- `/v1.48/debug/vars` - Runtime variables +- `/v1.48/debug/pprof/` - Profiling index +- `/v1.48/debug/pprof/cmdline` - Command line +- `/v1.48/debug/pprof/profile` - CPU profile +- `/v1.48/debug/pprof/trace` - Execution trace +- `/v1.48/debug/pprof/goroutine` - Goroutine stacks + +**How to use:** +```bash +# Access debug vars through versioned API +curl --unix-socket /var/run/docker.sock http://localhost/v1.48/debug/vars + +# Get CPU profile +curl --unix-socket /var/run/docker.sock http://localhost/v1.48/debug/pprof/profile?seconds=30 > profile.out +``` + +### 3. Component Updates + +**Latest versions in Engine 28.3.3:** +- Buildx v0.26.1 - Enhanced build performance +- Compose v2.40.3 - Latest compose features +- BuildKit v0.25.1 - Security improvements +- Go runtime 1.24.8 - Performance optimizations + +### 4. Security Fixes + +**CVE-2025-54388:** Fixed firewalld reload issue where published container ports could be accessed from local network even when bound to loopback. + +**Impact:** Critical for containers binding to 127.0.0.1 expecting localhost-only access. + +### 5. Deprecations + +**Raspberry Pi OS 32-bit (armhf):** +- Docker Engine 28 is the last major version supporting armhf +- Starting with Engine 29, no new armhf packages +- Migrate to 64-bit OS or use Engine 28.x LTS + +## Docker Desktop 4.47 Features (October 2025) + +### 1. MCP Catalog Integration + +**What it is:** +Model Context Protocol (MCP) server catalog with 100+ verified, containerized tools. + +**Key capabilities:** +- Discover and search MCP servers +- One-click deployment of MCP tools +- Integration with Docker AI and Model Runner +- Centralized management of AI agent tools + +**How to access:** +- Docker Hub MCP Catalog +- Docker Desktop MCP Toolkit +- Web: https://www.docker.com/mcp-catalog + +**Use cases:** +- AI agent tool discovery +- Workflow automation +- Development environment setup +- CI/CD tool integration + +### 2. Model Runner Enhancements + +**What's new:** +- Improved UI for model management +- Enhanced inference APIs +- Better inference engine performance +- Model card inspection in Docker Desktop +- `docker model requests` command for monitoring + +**How to use:** +```bash +# List running models +docker model ls + +# View model details (new: model cards) +docker model inspect llama2-7b + +# Monitor requests and responses (NEW) +docker model requests llama2-7b + +# Performance metrics +docker stats $(docker model ls -q) +``` + +### 3. Silent Component Updates + +**What it is:** +Docker Desktop automatically updates internal components without requiring full application restart. + +**Benefits:** +- Faster security patches +- Less disruption to workflow +- Automatic Compose, BuildKit, Containerd updates +- Background update delivery + +**Configuration:** +- Enabled by default +- Can be disabled in Settings > General +- Notifications for major updates only + +### 4. CVE Fixes + +**CVE-2025-10657 (v4.47):** Fixed Enhanced Container Isolation Docker Socket command restrictions not working in 4.46.0. + +**CVE-2025-9074 (v4.46):** Fixed malicious container escape allowing Docker Engine access without mounted socket. + +## Docker Desktop 4.38-4.45 Features + +### 1. Docker AI Assistant (Project Gordon) + +**What it is:** +AI-powered assistant integrated into Docker Desktop and CLI for intelligent container development. + +**Key capabilities:** +- Natural language command interface +- Context-aware troubleshooting +- Automated Dockerfile optimization +- Real-time best practice recommendations +- Intelligent error diagnosis + +**How to use:** +```bash +# Enable in Docker Desktop Settings > Features > Docker AI (Beta) + +# Ask questions in natural language +"Optimize my Python Dockerfile" +"Why is my container restarting?" +"Suggest secure nginx configuration" +``` + +**Local Model Runner:** +- Runs AI models directly on your machine (llama.cpp) +- No cloud API dependencies +- Privacy-preserving (data stays local) +- GPU acceleration for performance +- Works offline + +### 2. Enhanced Container Isolation (ECI) + +**What it is:** +Additional security layer that restricts Docker socket access and container escape vectors. + +**Security benefits:** +- Prevents unauthorized Docker socket access +- Restricts container capabilities by default +- Blocks common escape techniques +- Enforces stricter resource boundaries +- Audits container operations + +**How to enable:** +```bash +# Docker Desktop Settings > Security > Enhanced Container Isolation +# Or via CLI: +docker desktop settings set enhancedContainerIsolation=true +``` + +**Use cases:** +- Multi-tenant environments +- Security-critical applications +- Compliance requirements (PCI-DSS, HIPAA) +- Zero-trust architectures +- Development environments with untrusted code + +**Compatibility:** +- May break containers requiring Docker socket access +- Requires Docker Desktop 4.38+ +- Supported on Windows (WSL2), macOS, Linux Desktop + +### 3. Model Runner + +**What it is:** +Built-in AI model execution engine allowing developers to run large language models locally. + +**Features:** +- Run AI models without cloud services +- Optimal GPU acceleration +- Privacy-preserving inference +- Multiple model format support +- Integration with Docker AI + +**How to use:** +```bash +# Install via Docker Desktop Extensions +# Or use CLI: +docker model run llama2-7b + +# View running models: +docker model ls + +# Stop model: +docker model stop MODEL_ID +``` + +**Benefits:** +- No API costs +- Complete data privacy +- Offline availability +- Faster inference (local GPU) +- Integration with development workflow + +### 4. Multi-Node Kubernetes Testing + +**What it is:** +Test Kubernetes deployments with multi-node clusters directly in Docker Desktop. + +**Previously:** Single-node only +**Now:** 2-5 node clusters for realistic testing + +**How to enable:** +```bash +# Docker Desktop Settings > Kubernetes > Enable multi-node +# Specify node count (2-5) +``` + +**Use cases:** +- Test pod scheduling across nodes +- Validate affinity/anti-affinity rules +- Test network policies +- Simulate node failures +- Validate StatefulSets and DaemonSets + +### 5. Bake (General Availability) + +**What it is:** +High-level build orchestration tool for complex multi-target builds. + +**Previously:** Experimental +**Now:** Generally available and production-ready + +**Features:** +```hcl +# docker-bake.hcl +target "app" { + context = "." + dockerfile = "Dockerfile" + tags = ["myapp:latest"] + platforms = ["linux/amd64", "linux/arm64"] + cache-from = ["type=registry,ref=myapp:cache"] + cache-to = ["type=registry,ref=myapp:cache,mode=max"] +} + +target "test" { + inherits = ["app"] + target = "test" + output = ["type=local,dest=./coverage"] +} +``` + +```bash +# Build all targets +docker buildx bake + +# Build specific target +docker buildx bake test +``` + +## Moby 25 Engine Updates + +### Performance Improvements + +**1. Faster Container Startup:** +- 20-30% faster cold starts +- Improved layer extraction +- Optimized network initialization + +**2. Better Resource Management:** +- More accurate memory accounting +- Improved CPU throttling +- Better cgroup v2 support + +**3. Storage Driver Enhancements:** +- overlay2 performance improvements +- Better disk space management +- Faster image pulls + +### Security Updates + +**1. Enhanced Seccomp Profiles:** +```json +{ + "defaultAction": "SCMP_ACT_ERRNO", + "architectures": ["SCMP_ARCH_X86_64", "SCMP_ARCH_AARCH64"], + "syscalls": [ + { + "names": ["read", "write", "exit"], + "action": "SCMP_ACT_ALLOW" + } + ] +} +``` + +**2. Improved AppArmor Integration:** +- Better Docker profile generation +- Reduced false positives +- Enhanced logging + +**3. User Namespace Improvements:** +- Easier configuration +- Better compatibility +- Performance optimizations + +## Docker Compose v2.40.3+ Features (2025) + +### Compose Bridge (Convert to Kubernetes) + +**What it is:** +Convert local compose.yaml files to Kubernetes manifests in a single command. + +**Key capabilities:** +- Automatic conversion of Compose services to Kubernetes Deployments +- Service-to-Service mapping +- Volume conversion to PersistentVolumeClaims +- ConfigMap and Secret generation +- Ingress configuration + +**How to use:** +```bash +# Convert compose file to Kubernetes manifests +docker compose convert --format kubernetes > k8s-manifests.yaml + +# Or use compose-bridge directly +docker compose-bridge convert docker-compose.yml + +# Apply to Kubernetes cluster +kubectl apply -f k8s-manifests.yaml +``` + +**Example conversion:** +```yaml +# docker-compose.yml +services: + web: + image: nginx:latest + ports: + - "80:80" + volumes: + - data:/usr/share/nginx/html + +volumes: + data: + +# Converts to Kubernetes: +# - Deployment for 'web' service +# - Service exposing port 80 +# - PersistentVolumeClaim for 'data' +``` + +**Use cases:** +- Local development to Kubernetes migration +- Testing Kubernetes deployments locally +- CI/CD pipeline conversion +- Multi-environment deployment strategies + +### Breaking Changes + +**1. Version Field Obsolete:** +```yaml +# OLD (deprecated): +version: '3.8' +services: + app: + image: nginx + +# NEW (2025): +services: + app: + image: nginx +``` + +The `version` field is now ignored and can be omitted. + +### New Features + +**1. Develop Watch with initial_sync:** +```yaml +services: + app: + build: . + develop: + watch: + - action: sync + path: ./src + target: /app/src + initial_sync: full # NEW: Sync all files on start +``` + +**2. Volume Type: Image:** +```yaml +services: + app: + volumes: + - type: image + source: mydata:latest + target: /data + read_only: true +``` + +**3. Build Print:** +```bash +# Debug complex build configurations +docker compose build --print > build-config.json +``` + +**4. Config No-Env-Resolution:** +```bash +# View raw config without environment variable substitution +docker compose config --no-env-resolution +``` + +**5. Watch with Prune:** +```bash +# Automatically prune unused resources during watch +docker compose watch --prune +``` + +**6. Run with Quiet:** +```bash +# Reduce output noise +docker compose run --quiet app npm test +``` + +## BuildKit Updates (2025) + +### New Features + +**1. Git SHA-256 Support:** +```dockerfile +# Use SHA-256 based repositories +ADD https://github.com/user/repo#sha256:abc123... /src +``` + +**2. Enhanced COPY/ADD --exclude:** +```dockerfile +# Now generally available (was labs-only) +COPY --exclude=*.test.js --exclude=*.md . /app +``` + +**3. ADD --unpack with --chown:** +```dockerfile +# Extract and set ownership in one step +ADD --unpack=true --chown=appuser:appgroup archive.tar.gz /app +``` + +**4. Git Query Parameters:** +```dockerfile +# Fine-grained Git clone control +ADD https://github.com/user/repo.git?depth=1&branch=main /src +``` + +**5. Image Checksum Verification:** +```dockerfile +# Verify image integrity +FROM alpine:3.19@sha256:abc123... +# BuildKit verifies checksum automatically +``` + +### Security Enhancements + +**1. Improved Frontend Verification:** +```dockerfile +# Always use official Docker frontends +# syntax=docker/dockerfile:1 + +# Pin with digest for maximum security +# syntax=docker/dockerfile:1@sha256:ac85f380a63b13dfcefa89046420e1781752bab202122f8f50032edf31be0021 +``` + +**2. Remote Cache Improvements:** +- Fixed concurrency issues +- Better loop handling +- Enhanced security + +## Best Practices for 2025 Features + +### Using Docker AI Effectively + +**DO:** +- Provide specific context in queries +- Verify AI-generated configurations +- Combine with traditional security tools +- Use for learning and exploration + +**DON'T:** +- Trust AI blindly for security-critical apps +- Skip manual code review +- Ignore security scan results +- Use in air-gapped environments without Model Runner + +### Enhanced Container Isolation + +**DO:** +- Enable for security-sensitive workloads +- Test containers for compatibility first +- Document socket access requirements +- Use with least privilege principles + +**DON'T:** +- Enable without testing existing containers +- Disable without understanding risks +- Grant socket access unnecessarily +- Ignore audit logs + +### Modern Compose Files + +**DO:** +- Remove version field from new compose files +- Use new features (volume type: image, watch improvements) +- Leverage --print for debugging +- Adopt --quiet for cleaner CI/CD output + +**DON'T:** +- Keep version field (it's ignored anyway) +- Rely on deprecated syntax +- Skip testing with Compose v2.40+ +- Use outdated documentation + +## Migration Guide + +### Updating to Docker Desktop 4.38+ + +**1. Backup existing configurations:** +```bash +# Export current settings +docker context export desktop-linux > backup.tar +``` + +**2. Update Docker Desktop:** +- Download latest from docker.com +- Run installer +- Restart machine if required + +**3. Enable new features:** +```bash +# Enable AI Assistant (beta) +docker desktop settings set enableAI=true + +# Enable Enhanced Container Isolation +docker desktop settings set enhancedContainerIsolation=true +``` + +**4. Test existing containers:** +```bash +# Verify containers work with ECI +docker compose up -d +docker compose ps +docker compose logs +``` + +### Updating Compose Files + +**Before:** +```yaml +version: '3.8' + +services: + app: + image: nginx:latest + volumes: + - data:/data + +volumes: + data: +``` + +**After:** +```yaml +services: + app: + image: nginx:1.26.0 # Specific version + volumes: + - data:/data + develop: + watch: + - action: sync + path: ./config + target: /etc/nginx/conf.d + initial_sync: full + +volumes: + data: + driver: local +``` + +## Troubleshooting 2025 Features + +### Docker AI Issues + +**Problem:** AI Assistant not responding +**Solution:** +```bash +# Check Docker Desktop version +docker version + +# Ensure beta features enabled +docker desktop settings get enableAI + +# Restart Docker Desktop +``` + +**Problem:** Model Runner slow +**Solution:** +- Update GPU drivers +- Increase Docker Desktop memory (Settings > Resources) +- Close other GPU-intensive applications +- Use smaller models for faster inference + +### Enhanced Container Isolation Issues + +**Problem:** Container fails with socket permission error +**Solution:** +```bash +# Identify socket dependencies +docker inspect CONTAINER | grep -i socket + +# If truly needed, add socket access explicitly +# (Document why in docker-compose.yml comments) +docker run -v /var/run/docker.sock:/var/run/docker.sock ... +``` + +**Problem:** ECI breaks CI/CD pipeline +**Solution:** +- Disable ECI temporarily: `docker desktop settings set enhancedContainerIsolation=false` +- Review which containers need socket access +- Refactor to eliminate socket dependencies +- Re-enable ECI with exceptions documented + +### Compose v2.40 Issues + +**Problem:** "version field is obsolete" warning +**Solution:** +```yaml +# Simply remove the version field +# OLD: +version: '3.8' +services: ... + +# NEW: +services: ... +``` + +**Problem:** watch with initial_sync fails +**Solution:** +```bash +# Check file permissions +ls -la ./src + +# Ensure paths are correct +docker compose config | grep -A 5 watch + +# Verify sync target exists in container +docker compose exec app ls -la /app/src +``` + +## Recommended Feature Adoption Timeline + +**Immediate (Production-Ready):** +- Bake for complex builds +- Compose v2.40 features (remove version field) +- Moby 25 engine (via regular Docker updates) +- BuildKit improvements (automatic) + +**Testing (Beta but Stable):** +- Docker AI for development workflows +- Model Runner for local AI testing +- Multi-node Kubernetes for pre-production + +**Evaluation (Security-Critical):** +- Enhanced Container Isolation (test thoroughly) +- ECI with existing production containers +- Socket access elimination strategies + +This skill ensures you stay current with Docker's 2025 evolution while maintaining stability, security, and production-readiness. diff --git a/skills/docker-best-practices.md b/skills/docker-best-practices.md new file mode 100644 index 0000000..bf30ac1 --- /dev/null +++ b/skills/docker-best-practices.md @@ -0,0 +1,656 @@ +--- +name: docker-best-practices +description: Comprehensive Docker best practices for images, containers, and production deployments +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- βœ… CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# Docker Best Practices + +This skill provides current Docker best practices across all aspects of container development, deployment, and operation. + +## Image Best Practices + +### Base Image Selection + +**2025 Recommended Hierarchy:** +1. **Wolfi/Chainguard** (`cgr.dev/chainguard/*`) - Zero-CVE goal, SBOM included +2. **Alpine** (`alpine:3.19`) - ~7MB, minimal attack surface +3. **Distroless** (`gcr.io/distroless/*`) - ~2MB, no shell +4. **Slim variants** (`node:20-slim`) - ~70MB, balanced + +**Key rules:** +- Always specify exact version tags: `node:20.11.0-alpine3.19` +- Never use `latest` (unpredictable, breaks reproducibility) +- Use official images from trusted registries +- Match base image to actual needs + +### Dockerfile Structure + +**Optimal layer ordering** (least to most frequently changing): +```dockerfile +1. Base image and system dependencies +2. Application dependencies (package.json, requirements.txt, etc.) +3. Application code +4. Configuration and metadata +``` + +**Rationale:** Docker caches layers. If code changes but dependencies don't, cached dependency layers are reused, speeding up builds. + +**Example:** +```dockerfile +FROM python:3.12-slim + +# 1. System packages (rarely change) +RUN apt-get update && apt-get install -y --no-install-recommends \ + gcc \ + && rm -rf /var/lib/apt/lists/* + +# 2. Dependencies (change occasionally) +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +# 3. Application code (changes frequently) +COPY . /app +WORKDIR /app + +CMD ["python", "app.py"] +``` + +### Multi-Stage Builds + +Use multi-stage builds to separate build dependencies from runtime: + +```dockerfile +# Build stage +FROM node:20-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +RUN npm run build + +# Production stage +FROM node:20-alpine AS runtime +WORKDIR /app +# Only copy what's needed for runtime +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/node_modules ./node_modules +USER node +CMD ["node", "dist/server.js"] +``` + +**Benefits:** +- Smaller final images (no build tools) +- Better security (fewer attack vectors) +- Faster deployment (smaller upload/download) + +### Layer Optimization + +**Combine commands** to reduce layers and image size: + +```dockerfile +# Bad - 3 layers, cleanup doesn't reduce size +RUN apt-get update +RUN apt-get install -y curl +RUN rm -rf /var/lib/apt/lists/* + +# Good - 1 layer, cleanup effective +RUN apt-get update && \ + apt-get install -y --no-install-recommends curl && \ + rm -rf /var/lib/apt/lists/* +``` + +### .dockerignore + +Always create `.dockerignore` to exclude unnecessary files: + +``` +# Version control +.git +.gitignore + +# Dependencies +node_modules +__pycache__ +*.pyc + +# IDE +.vscode +.idea + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +logs/ + +# Testing +coverage/ +.nyc_output +*.test.js + +# Documentation +README.md +docs/ + +# Environment +.env +.env.local +*.local +``` + +## Container Runtime Best Practices + +### Security + +```bash +docker run \ + # Run as non-root + --user 1000:1000 \ + # Drop all capabilities, add only needed ones + --cap-drop=ALL \ + --cap-add=NET_BIND_SERVICE \ + # Read-only filesystem + --read-only \ + # Temporary writable filesystems + --tmpfs /tmp:noexec,nosuid \ + # No new privileges + --security-opt="no-new-privileges:true" \ + # Resource limits + --memory="512m" \ + --cpus="1.0" \ + my-image +``` + +### Resource Management + +Always set resource limits in production: + +```yaml +# docker-compose.yml +services: + app: + deploy: + resources: + limits: + cpus: '2.0' + memory: 1G + reservations: + cpus: '1.0' + memory: 512M +``` + +### Health Checks + +Implement health checks for all long-running containers: + +```dockerfile +HEALTHCHECK --interval=30s --timeout=3s --retries=3 --start-period=40s \ + CMD curl -f http://localhost:3000/health || exit 1 +``` + +Or in compose: +```yaml +services: + app: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost/health"] + interval: 30s + timeout: 3s + retries: 3 + start_period: 40s +``` + +### Logging + +Configure proper logging to prevent disk fill-up: + +```yaml +services: + app: + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" +``` + +Or system-wide in `/etc/docker/daemon.json`: +```json +{ + "log-driver": "json-file", + "log-opts": { + "max-size": "10m", + "max-file": "3" + } +} +``` + +### Restart Policies + +```yaml +services: + app: + # For development + restart: "no" + + # For production + restart: unless-stopped + + # Or with fine-grained control (Swarm mode) + deploy: + restart_policy: + condition: on-failure + delay: 5s + max_attempts: 3 + window: 120s +``` + +## Docker Compose Best Practices + +### File Structure + +```yaml +# No version field needed (Compose v2.40.3+) + +services: + # Service definitions + web: + # ... + api: + # ... + database: + # ... + +networks: + # Custom networks (preferred) + frontend: + backend: + internal: true + +volumes: + # Named volumes (preferred for persistence) + db-data: + app-data: + +configs: + # Configuration files (Swarm mode) + app-config: + file: ./config/app.conf + +secrets: + # Secrets (Swarm mode) + db-password: + file: ./secrets/db_pass.txt +``` + +### Network Isolation + +```yaml +networks: + frontend: + driver: bridge + backend: + driver: bridge + internal: true # No external access + +services: + web: + networks: + - frontend + + api: + networks: + - frontend + - backend + + database: + networks: + - backend # Not accessible from frontend +``` + +### Environment Variables + +```yaml +services: + app: + # Load from file (preferred for non-secrets) + env_file: + - .env + + # Inline for service-specific vars + environment: + - NODE_ENV=production + - LOG_LEVEL=info + + # For Swarm mode secrets + secrets: + - db_password +``` + +**Important:** +- Add `.env` to `.gitignore` +- Provide `.env.example` as template +- Never commit secrets to version control + +### Dependency Management + +```yaml +services: + api: + depends_on: + database: + condition: service_healthy # Wait for health check + redis: + condition: service_started # Just wait for start +``` + +## Production Best Practices + +### Image Tagging Strategy + +```bash +# Use semantic versioning +my-app:1.2.3 +my-app:1.2 +my-app:1 +my-app:latest + +# Include git commit for traceability +my-app:1.2.3-abc123f + +# Environment tags +my-app:1.2.3-production +my-app:1.2.3-staging +``` + +### Secrets Management + +**Never do this:** +```dockerfile +# BAD - secret in layer history +ENV API_KEY=secret123 +RUN echo "password" > /app/config +``` + +**Do this:** +```bash +# Use Docker secrets (Swarm) or external secret management +docker secret create db_password ./password.txt + +# Or mount secrets at runtime +docker run -v /secure/secrets:/run/secrets:ro my-app + +# Or use environment files (not in image) +docker run --env-file /secure/.env my-app +``` + +### Monitoring & Observability + +```yaml +services: + app: + # Health checks + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost/health"] + interval: 30s + + # Labels for monitoring tools + labels: + - "prometheus.io/scrape=true" + - "prometheus.io/port=9090" + - "com.company.team=backend" + - "com.company.version=1.2.3" + + # Logging + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" +``` + +### Backup Strategy + +```bash +# Backup named volume +docker run --rm \ + -v VOLUME_NAME:/data \ + -v $(pwd):/backup \ + alpine tar czf /backup/backup-$(date +%Y%m%d).tar.gz -C /data . + +# Restore volume +docker run --rm \ + -v VOLUME_NAME:/data \ + -v $(pwd):/backup \ + alpine tar xzf /backup/backup.tar.gz -C /data +``` + +### Update Strategy + +```yaml +services: + app: + # For Swarm mode - rolling updates + deploy: + replicas: 3 + update_config: + parallelism: 1 # Update 1 at a time + delay: 10s # Wait 10s between updates + failure_action: rollback + monitor: 60s + rollback_config: + parallelism: 1 + delay: 5s +``` + +## Platform-Specific Best Practices + +### Linux + +- Use user namespace remapping for added security +- Leverage native performance advantages +- Use Alpine for smallest images +- Configure SELinux/AppArmor profiles +- Use systemd for Docker daemon management + +```json +// /etc/docker/daemon.json +{ + "userns-remap": "default", + "log-driver": "json-file", + "log-opts": { + "max-size": "10m", + "max-file": "3" + }, + "storage-driver": "overlay2", + "live-restore": true +} +``` + +### macOS + +- Allocate sufficient resources in Docker Desktop +- Use `:delegated` or `:cached` for bind mounts +- Consider multi-platform builds for ARM (M1/M2) +- Limit file sharing to necessary directories + +```yaml +# Better volume performance on macOS +volumes: + - ./src:/app/src:delegated # Host writes are delayed + - ./build:/app/build:cached # Container writes are cached +``` + +### Windows + +- Choose container type: Windows or Linux +- Use forward slashes in paths +- Ensure drives are shared in Docker Desktop +- Be aware of line ending differences (CRLF vs LF) +- Consider WSL2 backend for better performance + +```yaml +# Windows-compatible paths +volumes: + - C:/Users/name/app:/app # Forward slashes work + # or + - C:\Users\name\app:/app # Backslashes need escaping in YAML +``` + +## Performance Best Practices + +### Build Performance + +```bash +# Use BuildKit (faster, better caching) +export DOCKER_BUILDKIT=1 + +# Use cache mounts +RUN --mount=type=cache,target=/root/.cache/pip \ + pip install -r requirements.txt + +# Use bind mounts for dependencies +RUN --mount=type=bind,source=package.json,target=package.json \ + --mount=type=bind,source=package-lock.json,target=package-lock.json \ + --mount=type=cache,target=/root/.npm \ + npm ci +``` + +### Image Size + +- Use multi-stage builds +- Choose minimal base images +- Clean up in the same layer +- Use .dockerignore +- Remove build dependencies + +```dockerfile +# Install and cleanup in one layer +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + package1 \ + package2 && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* +``` + +### Runtime Performance + +```dockerfile +# Use exec form (no shell overhead) +CMD ["node", "server.js"] # Good +# vs +CMD node server.js # Bad - spawns shell + +# Optimize signals +STOPSIGNAL SIGTERM + +# Run as non-root (slightly faster, much more secure) +USER appuser +``` + +## Security Best Practices Summary + +**Image Security:** +- Use official, minimal base images +- Scan for vulnerabilities (Docker Scout, Trivy) +- Don't include secrets in layers +- Run as non-root user +- Keep images updated + +**Runtime Security:** +- Drop capabilities +- Use read-only filesystem +- Set resource limits +- Enable security options +- Isolate networks +- Use secrets management + +**Compliance:** +- Follow CIS Docker Benchmark +- Implement container scanning in CI/CD +- Use signed images (Docker Content Trust) +- Maintain audit logs +- Regular security reviews + +## Common Anti-Patterns to Avoid + +❌ **Don't:** +- Run as root +- Use `--privileged` +- Mount Docker socket +- Use `latest` tag +- Hardcode secrets +- Skip health checks +- Ignore resource limits +- Use huge base images +- Skip vulnerability scanning +- Expose unnecessary ports +- Use inefficient layer caching +- Commit secrets to Git + +βœ… **Do:** +- Run as non-root +- Use minimal capabilities +- Isolate containers +- Tag with versions +- Use secrets management +- Implement health checks +- Set resource limits +- Use minimal images +- Scan regularly +- Apply least privilege +- Optimize build cache +- Use .env.example templates + +## Checklist for Production-Ready Images + +- [ ] Based on official, versioned, minimal image +- [ ] Multi-stage build (if applicable) +- [ ] Runs as non-root user +- [ ] No secrets in layers +- [ ] .dockerignore configured +- [ ] Vulnerability scan passed +- [ ] Health check implemented +- [ ] Proper labeling (version, description, etc.) +- [ ] Efficient layer caching +- [ ] Resource limits defined +- [ ] Logging configured +- [ ] Signals handled correctly +- [ ] Security options set +- [ ] Documentation complete +- [ ] Tested on target platform(s) + +This skill represents current Docker best practices. Always verify against official documentation for the latest recommendations, as Docker evolves continuously. diff --git a/skills/docker-git-bash-guide.md b/skills/docker-git-bash-guide.md new file mode 100644 index 0000000..c19fc29 --- /dev/null +++ b/skills/docker-git-bash-guide.md @@ -0,0 +1,543 @@ +--- +name: docker-git-bash-guide +description: Comprehensive Windows Git Bash and MINGW path conversion guide for Docker volume mounts and commands +--- + +# Docker on Windows Git Bash / MINGW - Path Conversion Guide + +This skill provides comprehensive guidance on handling Docker commands in Git Bash (MINGW) on Windows, with specific focus on volume mount path conversion issues and solutions. + +## The Path Conversion Problem + +When running Docker commands in Git Bash (MINGW) or MSYS2 on Windows, automatic path conversion can cause serious issues with volume mounts and other Docker commands. + +### What Triggers Automatic Conversion + +MSYS/MINGW shells automatically convert arguments that look like Unix paths when calling Windows executables (like `docker.exe`): + +**Examples of problematic conversions:** +```bash +# What you type: +docker run -v /c/Users/project:/app myimage + +# What Docker receives (BROKEN): +docker run -v C:\Program Files\Git\c\Users\project:/app myimage +``` + +**Triggers for path conversion:** +- Leading forward slash (`/`) in arguments +- Colon-separated path lists (`/foo:/bar`) +- Arguments with path components after `-` or `,` + +**What's exempt from conversion:** +- Arguments containing `=` (variable assignments) +- Drive letters (`C:`) +- Arguments with `;` (already Windows format) +- Arguments starting with `//` (network paths/Windows switches) + +## Shell Detection for Docker Commands + +### Detecting Git Bash / MINGW Environment + +Use these environment variables to detect when path conversion issues may occur: + +```bash +# Most reliable: Check for MSYSTEM +if [ -n "$MSYSTEM" ]; then + echo "Running in Git Bash/MINGW - path conversion needed" +fi + +# Alternative: Check uname +if [[ "$(uname -s)" == MINGW* ]]; then + echo "Running in MINGW environment" +fi + +# Environment variable to check: +# MSYSTEM values: MINGW64, MINGW32, MSYS +``` + +## Solution 1: MSYS_NO_PATHCONV (Recommended for Git Bash) + +The most reliable solution for Git Bash on Windows. + +### Per-Command Usage + +Prefix each Docker command with `MSYS_NO_PATHCONV=1`: + +```bash +# Volume mount with $(pwd) +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# Volume mount with absolute path +MSYS_NO_PATHCONV=1 docker run -v /c/Users/project:/app myimage + +# Multiple volume mounts +MSYS_NO_PATHCONV=1 docker run \ + -v $(pwd)/data:/data \ + -v $(pwd)/config:/etc/config \ + myimage +``` + +### Shell-Level Configuration + +Disable path conversion for all Docker commands in your session: + +```bash +# Add to ~/.bashrc or run in current shell +export MSYS_NO_PATHCONV=1 + +# Now all Docker commands work normally +docker run -v $(pwd):/app myimage +``` + +### Function Wrapper (Automatic per Docker Command) + +Create a function wrapper that automatically disables path conversion: + +```bash +# Add to ~/.bashrc +docker() { + (export MSYS_NO_PATHCONV=1; command docker.exe "$@") +} + +# Or using MSYS2_ARG_CONV_EXCL for MSYS2 +docker() { + (export MSYS2_ARG_CONV_EXCL='*'; command docker.exe "$@") +} + +# Make function available in subshells +export -f docker +``` + +## Solution 2: MSYS2_ARG_CONV_EXCL (MSYS2 Specific) + +For MSYS2 environments (not standard Git Bash): + +```bash +# Disable all argument conversion +export MSYS2_ARG_CONV_EXCL='*' + +# Selective exclusion (specific patterns) +export MSYS2_ARG_CONV_EXCL='--dir=;/test' + +# Environment variable conversion exclusion +export MSYS2_ENV_CONV_EXCL='*' +``` + +## Solution 3: Double Leading Slash + +Prefix paths with an extra `/` to prevent conversion: + +```bash +# Single slash (converted - BROKEN) +docker run -v /c/Users/project:/app myimage + +# Double slash (not converted - WORKS) +docker run -v //c/Users/project:/app myimage + +# Works in Git Bash on Windows +# Treated as single slash on Linux (portable) +``` + +**Advantages:** +- No environment variables needed +- Works without wrapper functions +- Portable (extra slash ignored on Linux) + +**Disadvantages:** +- Less readable +- Easy to forget +- Doesn't look like standard Docker syntax + +## Solution 4: Use $(pwd) with Proper Escaping + +Always use lowercase `$(pwd)` (not `$PWD`) with proper syntax: + +```bash +# CORRECT: Round brackets, lowercase pwd, no quotes +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# CORRECT: With subdirectories +MSYS_NO_PATHCONV=1 docker run -v $(pwd)/src:/app/src myimage + +# WRONG: Uppercase PWD variable (may not convert correctly) +docker run -v $PWD:/app myimage + +# WRONG: Without MSYS_NO_PATHCONV (path gets mangled) +docker run -v $(pwd):/app myimage +``` + +## Docker Volume Mount Best Practices (Git Bash on Windows) + +### For docker run Commands + +```bash +# Named volumes (no path conversion issue) +docker run -v my-named-volume:/data myimage + +# Bind mount with MSYS_NO_PATHCONV (RECOMMENDED) +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# Bind mount with double slash (ALTERNATIVE) +docker run -v //c/Users/project:/app myimage + +# Read-only bind mount +MSYS_NO_PATHCONV=1 docker run -v $(pwd)/config:/etc/config:ro myimage + +# Multiple volumes +MSYS_NO_PATHCONV=1 docker run \ + -v $(pwd)/src:/app/src \ + -v $(pwd)/data:/app/data \ + -v my-named-volume:/var/lib/data \ + myimage +``` + +### For docker-compose.yml Files + +Docker Compose files use forward slashes and relative paths - **these work correctly** in Git Bash: + +```yaml +# WORKS WITHOUT MODIFICATION in Git Bash +services: + app: + image: myimage + volumes: + # Relative paths (RECOMMENDED) + - ./src:/app/src + - ./data:/app/data + + # Named volumes (RECOMMENDED) + - my-data:/var/lib/data + + # Windows absolute paths with forward slashes (WORKS) + - C:/Users/project:/app + + # Unix-style paths (WORKS if referring to WSL/MINGW paths) + - /c/Users/project:/app + +volumes: + my-data: +``` + +**Important:** When running `docker compose` commands: + +```bash +# No special handling needed for compose files +docker compose up -d + +# But if you use command-line volume overrides: +MSYS_NO_PATHCONV=1 docker compose run -v $(pwd)/extra:/extra app +``` + +## Complete Examples + +### Example 1: Simple Application Development + +```bash +# Set up environment once per session +export MSYS_NO_PATHCONV=1 + +# Run with live code reload +docker run -d \ + --name dev-app \ + -v $(pwd)/src:/app/src \ + -v $(pwd)/public:/app/public \ + -p 3000:3000 \ + node:20-alpine \ + npm run dev + +# View logs +docker logs -f dev-app +``` + +### Example 2: Database with Data Persistence + +```bash +# Use named volume for database data (no path issues) +docker run -d \ + --name postgres-db \ + -e POSTGRES_PASSWORD=mypassword \ + -v pgdata:/var/lib/postgresql/data \ + -p 5432:5432 \ + postgres:16-alpine + +# Mount init scripts with MSYS_NO_PATHCONV +MSYS_NO_PATHCONV=1 docker run -d \ + --name postgres-db \ + -e POSTGRES_PASSWORD=mypassword \ + -v pgdata:/var/lib/postgresql/data \ + -v $(pwd)/init.sql:/docker-entrypoint-initdb.d/init.sql:ro \ + -p 5432:5432 \ + postgres:16-alpine +``` + +### Example 3: Full Stack with Docker Compose + +```bash +# Project structure: +# /c/Users/project/ +# β”œβ”€β”€ docker-compose.yml +# β”œβ”€β”€ backend/ +# β”œβ”€β”€ frontend/ +# └── data/ + +# docker-compose.yml (no special path handling needed) +cat > docker-compose.yml <<'EOF' +services: + backend: + build: ./backend + volumes: + - ./backend/src:/app/src + - ./data:/app/data + ports: + - "4000:4000" + + frontend: + build: ./frontend + volumes: + - ./frontend/src:/app/src + - ./frontend/public:/app/public + ports: + - "3000:3000" + depends_on: + - backend + + database: + image: postgres:16-alpine + volumes: + - db-data:/var/lib/postgresql/data + environment: + POSTGRES_PASSWORD: changeme + +volumes: + db-data: +EOF + +# Start everything (works normally) +docker compose up -d + +# Override with additional volume (needs MSYS_NO_PATHCONV) +MSYS_NO_PATHCONV=1 docker compose run -v $(pwd)/scripts:/scripts backend bash +``` + +## Troubleshooting Path Issues + +### Problem: "No such file or directory" errors + +**Symptoms:** +``` +Error response from daemon: invalid mount config for type "bind": +bind source path does not exist: C:\Program Files\Git\c\Users\project +``` + +**Diagnosis:** +- Path has been incorrectly converted by MINGW +- Notice `C:\Program Files\Git\` prefix added + +**Solution:** +```bash +# Add MSYS_NO_PATHCONV before command +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage +``` + +### Problem: Volume appears empty in container + +**Symptoms:** +- Container starts successfully +- But mounted directory is empty +- Files exist on host + +**Diagnosis:** +- Path conversion mangled the source path +- Docker created empty directory instead + +**Solution:** +```bash +# Use MSYS_NO_PATHCONV with $(pwd) +MSYS_NO_PATHCONV=1 docker run -v $(pwd)/data:/data myimage + +# Or use double slash +docker run -v //c/Users/project/data:/data myimage + +# Or use named volumes for persistent data +docker run -v my-named-volume:/data myimage +``` + +### Problem: Path with spaces fails + +**Symptoms:** +``` +Error: invalid reference format +``` + +**Diagnosis:** +- Spaces in Windows paths not properly quoted +- Path conversion + spaces = disaster + +**Solution:** +```bash +# Use MSYS_NO_PATHCONV and quote $(pwd) +MSYS_NO_PATHCONV=1 docker run -v "$(pwd)":/app myimage + +# Or avoid spaces in project paths entirely (RECOMMENDED) +# Move project from: +# C:/Users/My Name/My Projects/app +# To: +# C:/Users/MyName/projects/app +``` + +### Problem: $PWD not working correctly + +**Symptoms:** +- Using `$PWD` variable instead of `$(pwd)` +- Inconsistent behavior + +**Solution:** +```bash +# WRONG: Using $PWD +docker run -v $PWD:/app myimage + +# CORRECT: Using $(pwd) +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# Explanation: +# $(pwd) is a command that returns current directory +# $PWD is an environment variable that may not be properly formatted +``` + +## Testing Your Configuration + +Create a test script to verify Docker volume mounts work correctly: + +```bash +#!/bin/bash +# test-docker-volume.sh + +echo "Testing Docker volume mounts in Git Bash..." + +# Create test file +mkdir -p test-mount +echo "Hello from host" > test-mount/test.txt + +# Test 1: With MSYS_NO_PATHCONV +echo "Test 1: With MSYS_NO_PATHCONV" +MSYS_NO_PATHCONV=1 docker run --rm -v $(pwd)/test-mount:/data alpine cat /data/test.txt + +# Test 2: With double slash +echo "Test 2: With double slash" +docker run --rm -v //$(pwd)/test-mount:/data alpine cat /data/test.txt + +# Test 3: Without workaround (should fail) +echo "Test 3: Without workaround (may fail)" +docker run --rm -v $(pwd)/test-mount:/data alpine cat /data/test.txt + +# Cleanup +rm -rf test-mount + +echo "Testing complete!" +``` + +Run it: +```bash +chmod +x test-docker-volume.sh +./test-docker-volume.sh +``` + +## Recommended Configuration + +Add to your `~/.bashrc`: + +```bash +# Docker path conversion fix for Git Bash on Windows +export MSYS_NO_PATHCONV=1 + +# Or use a wrapper function if you prefer per-command control +docker() { + (export MSYS_NO_PATHCONV=1; command docker.exe "$@") +} +export -f docker + +# Alias for docker compose (if needed) +alias docker-compose='MSYS_NO_PATHCONV=1 docker compose' +``` + +## Platform Detection Script + +Use this to automatically detect and configure Docker for Git Bash: + +```bash +# Add to ~/.bashrc +# Detect if running in Git Bash/MINGW on Windows +if [ -n "$MSYSTEM" ] || [[ "$(uname -s)" == MINGW* ]]; then + # Running in Git Bash/MINGW + echo "Git Bash detected - enabling Docker path conversion fix" + export MSYS_NO_PATHCONV=1 + + # Optional: Create wrapper function for explicit control + docker() { + (export MSYS_NO_PATHCONV=1; command docker.exe "$@") + } + export -f docker +fi +``` + +## Quick Reference + +### Environment Variables + +| Variable | Purpose | Values | +|----------|---------|--------| +| `MSYS_NO_PATHCONV` | Disable all path conversion (Git Bash) | `1` to disable | +| `MSYS2_ARG_CONV_EXCL` | Exclude specific arguments (MSYS2) | `'*'` or patterns | +| `MSYS2_ENV_CONV_EXCL` | Exclude environment variables (MSYS2) | `'*'` or patterns | +| `MSYSTEM` | MSYS subsystem indicator | `MINGW64`, `MINGW32`, `MSYS` | + +### Command Patterns + +```bash +# RECOMMENDED: Export once per session +export MSYS_NO_PATHCONV=1 +docker run -v $(pwd):/app myimage + +# Per-command prefix +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# Double slash workaround +docker run -v //c/Users/project:/app myimage + +# Named volumes (no path issues) +docker run -v my-data:/data myimage + +# Docker Compose (relative paths work) +docker compose up -d +``` + +### What Works Without Modification + +These Docker commands work normally in Git Bash without special handling: + +- Named volumes: `-v my-volume:/data` +- Network commands: `docker network create` +- Image commands: `docker build`, `docker pull` +- Container commands without volumes: `docker run myimage` +- Docker Compose with relative paths in YAML + +### What Needs MSYS_NO_PATHCONV + +These commands require path conversion fixes: + +- Bind mounts with absolute paths: `-v /c/Users/project:/app` +- Bind mounts with $(pwd): `-v $(pwd):/app` +- Volume mounts on docker run command line +- Any command with Unix-style absolute paths + +## Summary + +**Best Practice for Git Bash on Windows:** + +1. **Add to ~/.bashrc:** `export MSYS_NO_PATHCONV=1` +2. **Use relative paths in docker-compose.yml:** `./src:/app/src` +3. **Use named volumes for data:** `my-data:/var/lib/data` +4. **Use $(pwd) with MSYS_NO_PATHCONV** for bind mounts: `MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app` + +This configuration ensures Docker commands work correctly in Git Bash on Windows without path conversion issues. diff --git a/skills/docker-platform-guide.md b/skills/docker-platform-guide.md new file mode 100644 index 0000000..4101ba5 --- /dev/null +++ b/skills/docker-platform-guide.md @@ -0,0 +1,753 @@ +--- +name: docker-platform-guide +description: Platform-specific Docker considerations for Windows, Linux, and macOS +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- βœ… CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# Docker Platform-Specific Guide + +This skill provides detailed guidance on Docker differences, considerations, and optimizations for Windows, Linux, and macOS platforms. + +## Linux + +### Advantages + +- **Native containers:** No virtualization layer overhead +- **Best performance:** Direct kernel features (cgroups, namespaces) +- **Full feature set:** All Docker features available +- **Production standard:** Most production deployments run on Linux +- **Flexibility:** Multiple distributions supported + +### Platform Features + +**Container Technologies:** +- Namespaces: PID, network, IPC, mount, UTS, user +- cgroups v1 and v2 for resource control +- Overlay2 storage driver (recommended) +- SELinux and AppArmor for mandatory access control + +**Storage Drivers:** +```bash +# Check current driver +docker info | grep "Storage Driver" + +# Recommended: overlay2 +# /etc/docker/daemon.json +{ + "storage-driver": "overlay2" +} +``` + +### Linux-Specific Configuration + +**Daemon Configuration** (`/etc/docker/daemon.json`): +```json +{ + "storage-driver": "overlay2", + "log-driver": "json-file", + "log-opts": { + "max-size": "10m", + "max-file": "3" + }, + "live-restore": true, + "userland-proxy": false, + "userns-remap": "default", + "icc": false, + "default-ulimits": { + "nofile": { + "Name": "nofile", + "Hard": 64000, + "Soft": 64000 + } + } +} +``` + +**User Namespace Remapping:** +```bash +# Enable in daemon.json +{ + "userns-remap": "default" +} + +# Restart Docker +sudo systemctl restart docker + +# Result: root in container = unprivileged user on host +``` + +### SELinux Integration + +```bash +# Check SELinux status +sestatus + +# Run container with SELinux enabled +docker run --security-opt label=type:svirt_sandbox_file_t myimage + +# Volume labels +docker run -v /host/path:/container/path:z myimage # Private label +docker run -v /host/path:/container/path:Z myimage # Shared label +``` + +### AppArmor Integration + +```bash +# Check AppArmor status +sudo aa-status + +# Run with default Docker profile +docker run --security-opt apparmor=docker-default myimage + +# Create custom profile +sudo aa-genprof docker run myimage +``` + +### Systemd Integration + +```bash +# Check Docker service status +sudo systemctl status docker + +# Enable on boot +sudo systemctl enable docker + +# Restart Docker +sudo systemctl restart docker + +# View logs +sudo journalctl -u docker -f + +# Configure service +sudo systemctl edit docker +``` + +### cgroup v1 vs v2 + +```bash +# Check cgroup version +stat -fc %T /sys/fs/cgroup/ + +# If using cgroup v2, ensure Docker version >= 20.10 + +# /etc/docker/daemon.json +{ + "exec-opts": ["native.cgroupdriver=systemd"] +} +``` + +### Linux Distribution Specifics + +**Ubuntu/Debian:** +```bash +# Install Docker +sudo apt-get update +sudo apt-get install ca-certificates curl +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc + +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io + +# Non-root user +sudo usermod -aG docker $USER +``` + +**RHEL/CentOS/Fedora:** +```bash +# Install Docker +sudo dnf -y install dnf-plugins-core +sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo +sudo dnf install docker-ce docker-ce-cli containerd.io + +# Start Docker +sudo systemctl start docker +sudo systemctl enable docker + +# Non-root user +sudo usermod -aG docker $USER +``` + +**Alpine:** +```bash +# Install Docker +apk add docker docker-compose + +# Start Docker +rc-update add docker boot +service docker start +``` + +## macOS + +### Architecture + +- **Docker Desktop:** Required (no native Docker on macOS) +- **Virtualization:** Uses HyperKit (Intel) or Virtualization.framework (Apple Silicon) +- **Linux VM:** Containers run in lightweight Linux VM +- **File sharing:** osxfs or VirtioFS for bind mounts + +### macOS-Specific Considerations + +**Resource Allocation:** +``` +Docker Desktop β†’ Preferences β†’ Resources β†’ Advanced +- CPUs: Allocate based on workload (default: half available) +- Memory: Allocate generously (default: 2GB, recommend 4-8GB) +- Swap: 1GB minimum +- Disk image size: 60GB+ for development +``` + +**File Sharing Performance:** + +Traditional osxfs is slow. Improvements: +1. **VirtioFS:** Enable in Docker Desktop settings (faster) +2. **Delegated/Cached mounts:** + +```yaml +volumes: + # Host writes delayed (best for source code) + - ./src:/app/src:delegated + + # Container writes cached (best for build outputs) + - ./build:/app/build:cached + + # Default consistency (slowest but safest) + - ./data:/app/data:consistent +``` + +**Network Access:** + +```bash +# Access host from container +host.docker.internal + +# Example: Connect to host PostgreSQL +docker run -e DATABASE_URL=postgresql://host.docker.internal:5432/db myapp +``` + +### Apple Silicon (M1/M2/M3) Specifics + +**Architecture Considerations:** +```bash +# Check image architecture +docker image inspect node:20-alpine | grep Architecture + +# M-series Macs are ARM64 +# Some images only available for AMD64 + +# Build multi-platform +docker buildx build --platform linux/amd64,linux/arm64 -t myapp . + +# Run AMD64 image on ARM (via emulation) +docker run --platform linux/amd64 myimage # Slower +``` + +**Rosetta 2 Integration:** +``` +Docker Desktop β†’ Features in development β†’ Use Rosetta for x86/amd64 emulation +``` +Faster AMD64 emulation on Apple Silicon. + +### macOS Docker Desktop Settings + +**General:** +- βœ… Start Docker Desktop when you log in +- βœ… Use VirtioFS (better performance) +- βœ… Use Virtualization framework (Apple Silicon) + +**Resources:** +``` +CPUs: 4-6 (for development) +Memory: 6-8 GB (for development) +Swap: 1-2 GB +Disk image size: 100+ GB (grows dynamically) +``` + +**Docker Engine:** +```json +{ + "builder": { + "gc": { + "enabled": true, + "defaultKeepStorage": "20GB" + } + }, + "experimental": false, + "features": { + "buildkit": true + } +} +``` + +### macOS File Permissions + +```bash +# macOS user ID and group ID +id -u # Usually 501 +id -g # Usually 20 + +# Match in container +docker run --user 501:20 myimage + +# Or in Dockerfile +RUN adduser -u 501 -g 20 appuser +USER appuser +``` + +### macOS Development Workflow + +```yaml +# docker-compose.yml for development +version: '3.8' + +services: + app: + build: . + volumes: + # Source code with delegated (better performance) + - ./src:/app/src:delegated + # node_modules in volume (much faster than bind mount) + - node_modules:/app/node_modules + ports: + - "3000:3000" + environment: + - NODE_ENV=development + +volumes: + node_modules: +``` + +### Common macOS Issues + +**Problem:** Slow file sync +**Solution:** +- Use VirtioFS +- Use delegated/cached mounts +- Store dependencies in volumes (not bind mounts) + +**Problem:** High CPU usage +**Solution:** +- Reduce file watching +- Exclude large directories from file sharing +- Allocate more resources + +**Problem:** Port already in use +**Solution:** +```bash +# Find process using port +lsof -i :PORT +kill -9 PID +``` + +## Windows + +### Windows Container Types + +**1. Linux Containers on Windows (LCOW):** +- Most common for development +- Uses WSL2 or Hyper-V backend +- Runs Linux containers +- Good compatibility + +**2. Windows Containers:** +- Native Windows containers +- For Windows-specific workloads +- Requires Windows Server base images +- Less common in development + +### Windows Backend Options + +**WSL2 Backend (Recommended):** +- Faster +- Better resource usage +- Native Linux kernel +- Requires Windows 10/11 (recent versions) + +**Hyper-V Backend:** +- Older option +- More resource intensive +- Works on older Windows versions + +### WSL2 Configuration + +**Enable WSL2:** +```powershell +# Run as Administrator +wsl --install + +# Or manually +dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart +dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart + +# Set WSL2 as default +wsl --set-default-version 2 + +# Install Ubuntu (or other distro) +wsl --install -d Ubuntu +``` + +**Docker Desktop Integration:** +``` +Settings β†’ Resources β†’ WSL Integration +- Enable integration with default distro +- Select additional distros +``` + +### Windows Path Considerations + +**Path Formats:** +```bash +# Forward slashes (recommended, works everywhere) +docker run -v C:/Users/name/project:/app myimage + +# Backslashes (need escaping in some contexts) +docker run -v C:\Users\name\project:/app myimage + +# In docker-compose.yml (forward slashes) +volumes: + - C:/Users/name/project:/app + +# Or relative paths +volumes: + - ./src:/app/src +``` + +### Git Bash / MINGW Path Conversion Issues + +**CRITICAL ISSUE:** When using Docker in Git Bash (MINGW) on Windows, automatic path conversion breaks volume mounts. + +**The Problem:** +```bash +# What you type in Git Bash: +docker run -v $(pwd):/app myimage + +# What Git Bash converts it to (BROKEN): +docker run -v C:\Program Files\Git\d\repos\project:/app myimage +``` + +**Solutions:** + +**1. MSYS_NO_PATHCONV (Recommended):** +```bash +# Per-command fix +MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage + +# Session-wide fix (add to ~/.bashrc) +export MSYS_NO_PATHCONV=1 + +# Function wrapper (automatic for all Docker commands) +docker() { + (export MSYS_NO_PATHCONV=1; command docker.exe "$@") +} +export -f docker +``` + +**2. Double Slash Workaround:** +```bash +# Use double leading slash to prevent conversion +docker run -v //c/Users/project:/app myimage + +# Works with $(pwd) too +docker run -v //$(pwd):/app myimage +``` + +**3. Named Volumes (No Path Issues):** +```bash +# Named volumes work without any fixes +docker run -v my-data:/data myimage +``` + +**What Works Without Modification:** +- Docker Compose YAML files with relative paths +- Named volumes +- Network and image commands +- Container commands without volumes + +**What Needs MSYS_NO_PATHCONV:** +- Bind mounts with `$(pwd)` +- Bind mounts with absolute Unix-style paths +- Volume mounts specified on command line + +**Shell Detection:** +```bash +# Detect Git Bash/MINGW and auto-configure +if [ -n "$MSYSTEM" ] || [[ "$(uname -s)" == MINGW* ]]; then + export MSYS_NO_PATHCONV=1 + echo "Git Bash detected - Docker path conversion fix enabled" +fi +``` + +**Recommended ~/.bashrc Configuration:** +```bash +# Docker on Git Bash fix +if [ -n "$MSYSTEM" ]; then + export MSYS_NO_PATHCONV=1 +fi +``` + +See the `docker-git-bash-guide` skill for comprehensive path conversion documentation, troubleshooting, and examples. + +### Windows File Sharing + +**Configure Shared Drives:** +``` +Docker Desktop β†’ Settings β†’ Resources β†’ File Sharing +Add: C:\, D:\, etc. +``` + +**Performance Considerations:** +- File sharing is slower than Linux/Mac +- Use WSL2 backend for better performance +- Store frequently accessed files in WSL2 filesystem + +### Windows Line Endings + +**Problem:** CRLF vs LF line endings + +**Solution:** +```bash +# Git configuration +git config --global core.autocrlf input + +# Or per-repo (.gitattributes) +* text=auto +*.sh text eol=lf +*.bat text eol=crlf +``` + +```dockerfile +# In Dockerfile for scripts +FROM alpine +COPY --chmod=755 script.sh / +# Ensure LF endings +RUN dos2unix /script.sh || sed -i 's/\r$//' /script.sh +``` + +### Windows Firewall + +```powershell +# Allow Docker Desktop +New-NetFirewallRule -DisplayName "Docker Desktop" -Direction Inbound -Program "C:\Program Files\Docker\Docker\Docker Desktop.exe" -Action Allow + +# Check blocked ports +netstat -ano | findstr :PORT +``` + +### Windows-Specific Docker Commands + +```powershell +# Run PowerShell in container +docker run -it mcr.microsoft.com/powershell:lts-7.4-windowsservercore-ltsc2022 + +# Windows container example +docker run -it mcr.microsoft.com/windows/servercore:ltsc2022 cmd + +# Check container type +docker info | Select-String "OSType" +``` + +### WSL2 Disk Management + +**Problem:** WSL2 VHDX grows but doesn't shrink + +**Solution:** +```powershell +# Stop Docker Desktop and WSL +wsl --shutdown + +# Compact disk image (run as Administrator) +# Method 1: Optimize-VHD (requires Hyper-V tools) +Optimize-VHD -Path "$env:LOCALAPPDATA\Docker\wsl\data\ext4.vhdx" -Mode Full + +# Method 2: diskpart +diskpart +# In diskpart: +select vdisk file="C:\Users\YourName\AppData\Local\Docker\wsl\data\ext4.vhdx" +attach vdisk readonly +compact vdisk +detach vdisk +exit +``` + +### Windows Development Workflow + +```yaml +# docker-compose.yml for Windows +version: '3.8' + +services: + app: + build: . + volumes: + # Use forward slashes + - ./src:/app/src + # Named volumes for better performance + - node_modules:/app/node_modules + ports: + - "3000:3000" + environment: + - NODE_ENV=development + # Windows-specific: ensure proper line endings + command: sh -c "dos2unix /app/scripts/*.sh && npm start" + +volumes: + node_modules: +``` + +### Common Windows Issues + +**Problem:** Permission denied errors +**Solution:** +```powershell +# Run Docker Desktop as Administrator +# Or grant permissions to Docker Desktop +icacls "C:\ProgramData\DockerDesktop" /grant Users:F /T +``` + +**Problem:** Slow performance +**Solution:** +- Use WSL2 backend +- Store project in WSL2 filesystem (`\\wsl$\Ubuntu\home\user\project`) +- Use named volumes for node_modules, etc. + +**Problem:** Path not found +**Solution:** +- Use forward slashes +- Ensure drive is shared in Docker Desktop +- Use absolute paths or `${PWD}` + +## Platform Comparison + +| Feature | Linux | macOS | Windows | +|---------|-------|-------|---------| +| **Performance** | Excellent (native) | Good (VM overhead) | Good (WSL2) to Fair (Hyper-V) | +| **File sharing** | Native | Slow (improving with VirtioFS) | Slow (better in WSL2) | +| **Resource efficiency** | Best | Good | Good (WSL2) | +| **Feature set** | Complete | Complete | Complete (LCOW) | +| **Production** | Standard | Dev only | Dev only (LCOW) | +| **Ease of use** | Moderate | Easy (Docker Desktop) | Easy (Docker Desktop) | +| **Cost** | Free | Free (Docker Desktop Personal) | Free (Docker Desktop Personal) | + +## Cross-Platform Best Practices + +### Multi-Platform Images + +```bash +# Create buildx builder +docker buildx create --name multiplatform --driver docker-container --use + +# Build for multiple platforms +docker buildx build \ + --platform linux/amd64,linux/arm64,linux/arm/v7 \ + -t myimage:latest \ + --push \ + . +``` + +### Platform-Agnostic Dockerfiles + +```dockerfile +# Works on all platforms +FROM node:20-alpine + +# Use COPY with --chmod (not RUN chmod, which is slower) +COPY --chmod=755 script.sh /usr/local/bin/ + +# Use environment variables for paths +ENV APP_HOME=/app +WORKDIR ${APP_HOME} + +# Use exec form for CMD/ENTRYPOINT (works on Windows containers too) +CMD ["node", "server.js"] +``` + +### Cross-Platform Compose Files + +```yaml +version: '3.8' + +services: + app: + build: . + volumes: + # Relative paths work everywhere + - ./src:/app/src + # Named volumes (platform-agnostic) + - data:/app/data + environment: + # Use environment variables + - NODE_ENV=${NODE_ENV:-development} + +volumes: + data: +``` + +### Testing Across Platforms + +```bash +# Test on different platforms with buildx +docker buildx build --platform linux/amd64 -t myapp:amd64 --load . +docker run --rm myapp:amd64 + +docker buildx build --platform linux/arm64 -t myapp:arm64 --load . +docker run --rm myapp:arm64 +``` + +## Platform Selection Guide + +**Choose Linux for:** +- Production deployments +- Maximum performance +- Full Docker feature set +- Minimal overhead +- CI/CD pipelines + +**Choose macOS for:** +- Development on Mac hardware +- When you need macOS tools +- Docker Desktop ease of use +- M1/M2/M3 development + +**Choose Windows for:** +- Development on Windows hardware +- Windows-specific applications +- When team uses Windows +- WSL2 for better Linux container support + +This platform guide covers the major differences. Always test on your target deployment platform before going to production. diff --git a/skills/docker-security-guide.md b/skills/docker-security-guide.md new file mode 100644 index 0000000..66a8510 --- /dev/null +++ b/skills/docker-security-guide.md @@ -0,0 +1,1004 @@ +--- +name: docker-security-guide +description: Comprehensive Docker security guidelines and threat mitigation strategies +--- + +## 🚨 CRITICAL GUIDELINES + +### Windows File Path Requirements + +**MANDATORY: Always Use Backslashes on Windows for File Paths** + +When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). + +**Examples:** +- ❌ WRONG: `D:/repos/project/file.tsx` +- βœ… CORRECT: `D:\repos\project\file.tsx` + +This applies to: +- Edit tool file_path parameter +- Write tool file_path parameter +- All file operations on Windows systems + + +### Documentation Guidelines + +**NEVER create new documentation files unless explicitly requested by the user.** + +- **Priority**: Update existing README.md files rather than creating new documentation +- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise +- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone +- **User preference**: Only create additional .md files when user specifically asks for documentation + + +--- + +# Docker Security Guide + +This skill provides comprehensive security guidelines for Docker across all platforms, covering threats, mitigations, and compliance requirements. + +## Security Principles + +### Defense in Depth + +Apply security at multiple layers: +1. **Image security:** Minimal, scanned, signed images +2. **Build security:** Secure build process, no secrets in layers +3. **Runtime security:** Restricted capabilities, resource limits +4. **Network security:** Isolation, least privilege +5. **Host security:** Hardened host OS, updated Docker daemon +6. **Orchestration security:** Secure configuration, RBAC +7. **Monitoring:** Detection, logging, alerting + +### Least Privilege + +Grant only the minimum permissions necessary: +- Non-root users +- Dropped capabilities +- Read-only filesystems +- Minimal network exposure +- Restricted syscalls (seccomp) +- Limited resources + +## Image Security + +### Base Image Selection + +**Threat:** Vulnerable or malicious base images + +**Mitigation:** +```dockerfile +# Use official images only +FROM node:20.11.0-alpine3.19 # Official, specific version + +# NOT +FROM randomuser/node # Unverified source +FROM node:latest # Unpredictable, can break +``` + +**Verification:** +```bash +# Verify image source +docker image inspect node:20-alpine | grep -A 5 "Author" + +# Enable Docker Content Trust (image signing) +export DOCKER_CONTENT_TRUST=1 +docker pull node:20-alpine +``` + +### Minimal Images + +**Threat:** Larger attack surface, more vulnerabilities + +**Mitigation:** +```dockerfile +# Prefer minimal distributions +FROM alpine:3.19 # ~7MB +FROM gcr.io/distroless/static # ~2MB +FROM scratch # 0MB (for static binaries) + +# vs +FROM ubuntu:22.04 # ~77MB with more packages +``` + +**Benefits:** +- Fewer packages = fewer vulnerabilities +- Smaller attack surface +- Faster downloads and starts +- Less disk space + +### Micro-Distros for Security-Critical Applications (2025) + +**Wolfi/Chainguard Images:** +- Zero-CVE goal, SBOM included by default +- Nightly security patches, signed with provenance +- Available for: Node, Python, Go, Java, .NET, etc. + +**Usage:** +```dockerfile +# Development stage (includes build tools) +FROM cgr.dev/chainguard/node:latest-dev AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production + +# Production stage (minimal, zero-CVE goal) +FROM cgr.dev/chainguard/node:latest +WORKDIR /app +COPY --from=builder /app/node_modules ./node_modules +COPY . . +USER node +ENTRYPOINT ["node", "server.js"] +``` + +**When to use:** Security-critical apps, compliance requirements (SOC2, HIPAA, PCI-DSS), zero-trust environments, supply chain security emphasis. + +See `docker-best-practices` skill for full image comparison table. + +### Vulnerability Scanning + +**Tools:** +- Docker Scout (built-in) +- Trivy +- Grype +- Snyk +- Clair + +**Process:** +```bash +# Scan with Docker Scout +docker scout cves IMAGE_NAME +docker scout recommendations IMAGE_NAME + +# Scan with Trivy +trivy image IMAGE_NAME +trivy image --severity HIGH,CRITICAL IMAGE_NAME + +# Scan Dockerfile +trivy config Dockerfile + +# Scan for secrets +trivy fs --scanners secret . +``` + +**CI/CD Integration:** +```yaml +# GitHub Actions example +- name: Scan image + run: | + docker scout cves my-image:${{ github.sha }} + trivy image --exit-code 1 --severity CRITICAL my-image:${{ github.sha }} +``` + +### Multi-Stage Builds for Security + +**Threat:** Build tools and secrets in final image + +**Mitigation:** +```dockerfile +# Build stage with build tools +FROM golang:1.21 AS builder +WORKDIR /app +COPY . . +RUN go build -o app + +# Final stage - minimal, no build tools +FROM gcr.io/distroless/base-debian11 +COPY --from=builder /app/app / +USER nonroot:nonroot +ENTRYPOINT ["/app"] +``` + +**Benefits:** +- No compiler/build tools in production image +- Secrets used in build don't persist +- Smaller, more secure final image + +## Build-Time Security + +### Secrets Management + +**NEVER:** +```dockerfile +# BAD - Secret in layer history +ENV API_KEY=abc123 +RUN git clone https://user:password@github.com/repo.git +COPY .env /app/.env +``` + +**DO:** +```dockerfile +# Use BuildKit secrets +# syntax=docker/dockerfile:1 + +FROM alpine +RUN --mount=type=secret,id=github_token \ + git clone https://$(cat /run/secrets/github_token)@github.com/repo.git +``` + +```bash +# Build with secret (not in image) +docker build --secret id=github_token,src=./token.txt . +``` + +### BuildKit Frontend Security (2025) + +**Threat:** Malicious or compromised BuildKit frontends can execute arbitrary code during build + +**🚨 2025 CRITICAL WARNING:** BuildKit supports custom frontends (parsers) via `# syntax=` directive. Untrusted frontends have FULL BUILD-TIME code execution and can: +- Steal secrets from build context +- Modify build outputs +- Exfiltrate data +- Compromise the build environment + +**Risk Example:** +```dockerfile +# πŸ”΄ DANGER - Untrusted frontend (code execution risk!) +# syntax=docker/dockerfile:1@sha256:abc123...untrusted + +FROM alpine +RUN echo "This frontend could do anything during build" +``` + +**Mitigation:** + +1. **Only use official Docker frontends:** +```dockerfile +# βœ… Safe - Official Docker frontend +# syntax=docker/dockerfile:1 + +# βœ… Safe - Specific version +# syntax=docker/dockerfile:1.5 + +# βœ… Safe - Pinned with digest (verify from docker.com) +# syntax=docker/dockerfile:1@sha256:ac85f380a63b13dfcefa89046420e1781752bab202122f8f50032edf31be0021 +``` + +2. **Verify frontend sources:** +- Use ONLY `docker/dockerfile:*` frontends +- Pin to specific versions with SHA256 digest +- Verify digests from official Docker documentation +- Never use third-party frontends without thorough vetting + +3. **Audit all Dockerfiles for unsafe syntax directives:** +```bash +# Check all Dockerfiles for potentially malicious syntax directives +grep -r "^# syntax=" . --include="Dockerfile*" + +# Verify all frontends are official Docker images +grep -r "^# syntax=" . --include="Dockerfile*" | grep -v "docker/dockerfile" +``` + +4. **BuildKit security configuration (defense in depth):** +```bash +# Restrict frontend sources in BuildKit config +# /etc/buildkit/buildkitd.toml +[frontend."dockerfile.v0"] + # Only allow official Docker frontends + allowedImages = ["docker.io/docker/dockerfile:*"] +``` + +**Supply Chain Protection:** +- Treat custom frontends as HIGH RISK code execution vectors +- Review ALL `# syntax=` directives in Dockerfiles before builds +- Use content trust for frontend images +- Monitor for frontend vulnerabilities +- Include frontend verification in CI/CD security gates + +### SBOM (Software Bill of Materials) Generation (2025) + +**Critical 2025 Requirement:** Document origin and history of all components for supply chain transparency and compliance. + +**Why SBOM is Mandatory:** +- Supply chain security visibility +- Vulnerability tracking and response +- Compliance requirements (Executive Order 14028, etc.) +- License compliance +- Incident response readiness + +**Generate SBOM with Docker Scout:** +```bash +# Generate SBOM for image +docker scout sbom IMAGE_NAME + +# Export SBOM in different formats +docker scout sbom --format spdx IMAGE_NAME > sbom.spdx.json +docker scout sbom --format cyclonedx IMAGE_NAME > sbom.cyclonedx.json + +# Include SBOM attestation during build +# ⚠️ WARNING: BuildKit attestations are NOT cryptographically signed! +docker buildx build \ + --sbom=true \ + --provenance=true \ + --tag my-image:latest \ + . + +# View SBOM attestations (unsigned metadata only) +docker buildx imagetools inspect my-image:latest --format "{{ json .SBOM }}" +``` + +**🚨 CRITICAL SECURITY LIMITATION:** +BuildKit attestations (`--sbom=true`, `--provenance=true`) are **NOT cryptographically signed**. This means: +- Anyone with push access can create tampered attestations +- SBOMs can be incomplete or falsified +- Provenance data cannot be trusted without external verification +- **For production:** Use external signing tools (cosign, Notary) and Syft for SBOM generation + +**Generate SBOM with Syft:** +```bash +# Install Syft +curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh + +# Generate SBOM from image +syft my-image:latest + +# Generate in specific format +syft my-image:latest -o spdx-json > sbom.spdx.json +syft my-image:latest -o cyclonedx-json > sbom.cyclonedx.json + +# Generate from Dockerfile +syft dir:. -o spdx-json > sbom.spdx.json +``` + +**SBOM in CI/CD Pipeline:** +```yaml +# GitHub Actions example +name: Build with SBOM + +jobs: + build: + steps: + - name: Build image with SBOM + run: | + docker buildx build \ + --sbom=true \ + --provenance=true \ + --tag my-image:${{ github.sha }} \ + --push \ + . + + - name: Generate SBOM with Syft + run: | + syft my-image:${{ github.sha }} -o spdx-json > sbom.json + + - name: Upload SBOM artifact + uses: actions/upload-artifact@v3 + with: + name: sbom + path: sbom.json + + - name: Scan SBOM for vulnerabilities + run: | + grype sbom:sbom.json --fail-on high +``` + +**SBOM Best Practices:** + +1. **Generate for every image:** + - Production images: mandatory + - Development images: recommended + - Base images: critical + +2. **Store SBOMs with provenance:** + - Version control alongside Dockerfile + - Artifact registry with image + - Dedicated SBOM repository + +3. **Automate SBOM generation:** + - Integrate into CI/CD pipeline + - Generate on every build + - Fail builds if SBOM generation fails + +4. **Use SBOM for vulnerability management:** +```bash +# Scan SBOM instead of image (faster) +grype sbom:sbom.json +trivy sbom sbom.json + +# Compare SBOMs between versions +diff <(syft old-image:1.0 -o json) <(syft new-image:2.0 -o json) +``` + +5. **SBOM formats:** + - **SPDX:** Industry standard, ISO/IEC 5962:2021 + - **CycloneDX:** OWASP standard, security-focused + - Choose based on compliance requirements + +**Chainguard Images with Built-in SBOM:** +```bash +# Chainguard images include SBOM attestation by default +docker buildx imagetools inspect cgr.dev/chainguard/node:latest + +# Extract SBOM +cosign download sbom cgr.dev/chainguard/node:latest > chainguard-node-sbom.json +``` + +**Or use multi-stage and don't include secrets:** +```dockerfile +FROM node AS builder +ARG NPM_TOKEN +RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && \ + npm install && \ + rm .npmrc # Still in layer history! + +# Better - secret only in build stage +FROM node AS dependencies +RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ + npm install + +FROM node AS runtime +COPY --from=dependencies /app/node_modules ./node_modules +# No .npmrc in final image +``` + +### Secure Build Context + +**Threat:** Sensitive files included in build context + +**Mitigation:** +Create comprehensive `.dockerignore`: +``` +# Secrets +.env +.env.local +*.key +*.pem +credentials.json +secrets/ + +# Version control +.git +.gitignore + +# Cloud credentials +.aws/ +.gcloud/ + +# Private data +database.sql +backups/ + +# SSH keys +.ssh/ +id_rsa +id_rsa.pub + +# Sensitive logs +*.log +logs/ +``` + +### Image Signing + +**Enable Docker Content Trust:** +```bash +# Enable image signing +export DOCKER_CONTENT_TRUST=1 + +# Set up keys +docker trust key generate my-key +docker trust signer add --key my-key.pub my-name my-image + +# Push signed image +docker push my-image:tag + +# Pull only signed images +docker pull my-image:tag # Fails if not signed +``` + +## Runtime Security + +### User Privileges + +**Threat:** Container escape via root + +**Mitigation:** +```dockerfile +# Create and use non-root user +FROM node:20-alpine +RUN addgroup -g 1001 appuser && \ + adduser -S appuser -u 1001 -G appuser +USER appuser +WORKDIR /home/appuser/app +COPY --chown=appuser:appuser . . +CMD ["node", "server.js"] +``` + +**Verification:** +```bash +# Check user in running container +docker exec container-name whoami # Should not be root +docker exec container-name id # Check UID/GID +``` + +### Capabilities + +**Threat:** Excessive kernel capabilities + +**Default Docker capabilities:** +- CHOWN, DAC_OVERRIDE, FOWNER, FSETID +- KILL, SETGID, SETUID, SETPCAP +- NET_BIND_SERVICE, NET_RAW +- SYS_CHROOT, MKNOD, AUDIT_WRITE, SETFCAP + +**Mitigation:** +```bash +# Drop all, add only needed +docker run \ + --cap-drop=ALL \ + --cap-add=NET_BIND_SERVICE \ + my-image +``` + +**In docker-compose.yml:** +```yaml +services: + app: + cap_drop: + - ALL + cap_add: + - NET_BIND_SERVICE +``` + +**Common needed capabilities:** +- `NET_BIND_SERVICE`: Bind to ports < 1024 +- `NET_ADMIN`: Network configuration +- `SYS_TIME`: Set system time + +### Read-Only Filesystem + +**Threat:** Container modification, malware persistence + +**Mitigation:** +```bash +docker run \ + --read-only \ + --tmpfs /tmp:noexec,nosuid,size=64M \ + --tmpfs /var/run:noexec,nosuid,size=64M \ + my-image +``` + +**In Compose:** +```yaml +services: + app: + read_only: true + tmpfs: + - /tmp:noexec,nosuid,size=64M + - /var/run:noexec,nosuid,size=64M +``` + +### Security Options + +**no-new-privileges:** +```bash +docker run --security-opt="no-new-privileges:true" my-image +``` + +Prevents privilege escalation via setuid/setgid binaries. + +**AppArmor (Linux):** +```bash +docker run --security-opt="apparmor=docker-default" my-image +``` + +**SELinux (Linux):** +```bash +docker run --security-opt="label=type:container_runtime_t" my-image +``` + +**Seccomp (syscall filtering):** +```bash +# Use default profile +docker run --security-opt="seccomp=default" my-image + +# Or custom profile +docker run --security-opt="seccomp=./seccomp-profile.json" my-image +``` + +### Resource Limits + +**Threat:** DoS via resource exhaustion + +**Mitigation:** +```bash +docker run \ + --memory="512m" \ + --memory-swap="512m" \ # Disable swap + --cpus="1.0" \ + --pids-limit=100 \ + --ulimit nofile=1024:1024 \ + my-image +``` + +**In Compose:** +```yaml +services: + app: + deploy: + resources: + limits: + cpus: '1.0' + memory: 512M + pids: 100 + reservations: + cpus: '0.5' + memory: 256M + ulimits: + nofile: + soft: 1024 + hard: 1024 +``` + +### Comprehensive Secure Run Command + +```bash +docker run \ + --name secure-app \ + --detach \ + --restart unless-stopped \ + --user 1000:1000 \ + --cap-drop=ALL \ + --cap-add=NET_BIND_SERVICE \ + --read-only \ + --tmpfs /tmp:noexec,nosuid,size=64M \ + --security-opt="no-new-privileges:true" \ + --security-opt="seccomp=default" \ + --memory="512m" \ + --cpus="1.0" \ + --pids-limit=100 \ + --network=isolated-network \ + --publish 127.0.0.1:8080:8080 \ + --volume secure-data:/data:ro \ + --health-cmd="curl -f http://localhost/health || exit 1" \ + --health-interval=30s \ + my-secure-image:1.2.3 +``` + +## Network Security + +### Network Isolation + +**Threat:** Lateral movement between containers + +**Mitigation:** +```yaml +networks: + frontend: + driver: bridge + backend: + driver: bridge + internal: true # No external access + +services: + web: + networks: + - frontend + + api: + networks: + - frontend + - backend + + database: + networks: + - backend # Isolated from frontend +``` + +### Port Exposure + +**Threat:** Unnecessary network exposure + +**Mitigation:** +```bash +# Bind to localhost only +docker run -p 127.0.0.1:8080:8080 my-image + +# NOT (binds to all interfaces) +docker run -p 8080:8080 my-image +``` + +**In Compose:** +```yaml +services: + app: + ports: + - "127.0.0.1:8080:8080" # Localhost only +``` + +### Inter-Container Communication + +```yaml +# Disable default inter-container communication +# /etc/docker/daemon.json +{ + "icc": false +} +``` + +Then explicitly allow via networks: +```yaml +services: + app1: + networks: + - app-network + app2: + networks: + - app-network # Can communicate with app1 + +networks: + app-network: + driver: bridge +``` + +## Secrets Management + +### Docker Secrets (Swarm Mode) + +```bash +# Create secret +echo "mypassword" | docker secret create db_password - + +# Use in service +docker service create \ + --name my-service \ + --secret db_password \ + my-image + +# Access in container at /run/secrets/db_password +``` + +**In stack file:** +```yaml +version: '3.8' + +services: + app: + image: my-image + secrets: + - db_password + +secrets: + db_password: + external: true +``` + +### Secrets Best Practices + +1. **Never in environment variables** (visible in `docker inspect`) +2. **Never in images** (in layer history) +3. **Never in version control** (Git history) +4. **Mount as files** with restricted permissions +5. **Use secret management systems** (Vault, AWS Secrets Manager, etc.) +6. **Rotate regularly** + +**Alternative: Mounted secrets:** +```bash +docker run -v /secure/secrets:/run/secrets:ro my-image +``` + +## Compliance & Benchmarking + +### CIS Docker Benchmark + +Automated checking: +```bash +# Clone docker-bench-security +git clone https://github.com/docker/docker-bench-security.git +cd docker-bench-security +sudo sh docker-bench-security.sh + +# Or run as container +docker run --rm --net host --pid host --userns host \ + --cap-add audit_control \ + -v /var/lib:/var/lib:ro \ + -v /var/run/docker.sock:/var/run/docker.sock:ro \ + -v /usr/lib/systemd:/usr/lib/systemd:ro \ + -v /etc:/etc:ro \ + docker/docker-bench-security +``` + +### Key CIS Recommendations + +1. **Host Configuration** + - Keep Docker up to date + - Restrict network traffic between containers + - Set logging level to 'info' + - Enable Docker Content Trust + +2. **Docker Daemon** + - Use TLS for Docker daemon socket + - Don't expose daemon on TCP without TLS + - Enable user namespace support + +3. **Docker Files** + - Verify Docker files ownership and permissions + - Audit Docker files and directories + +4. **Container Images** + - Create user for container + - Use trusted base images + - Don't install unnecessary packages + +5. **Container Runtime** + - Run containers with limited privileges + - Set resource limits + - Don't share host network namespace + +## Monitoring & Detection + +### Logging + +```yaml +services: + app: + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + labels: "service,env" + env: "ENV,VERSION" +``` + +**Centralized logging:** +```yaml +services: + app: + logging: + driver: "syslog" + options: + syslog-address: "tcp://log-server:514" + tag: "{{.Name}}/{{.ID}}" +``` + +### Runtime Monitoring + +**Tools:** +- Falco: Runtime security monitoring +- Sysdig: Container visibility +- Prometheus + cAdvisor: Metrics +- Docker events: Real-time events + +**Monitor for:** +- Unexpected processes +- File modifications +- Network connections +- Resource spikes +- Failed authentication +- Privilege escalation attempts + +```bash +# Monitor Docker events +docker events --filter 'type=container' --filter 'event=start' + +# Watch specific container +docker events --filter "container=my-container" + +# Runtime security with Falco +docker run --rm -it \ + --privileged \ + -v /var/run/docker.sock:/host/var/run/docker.sock \ + -v /dev:/host/dev \ + -v /proc:/host/proc:ro \ + falcosecurity/falco +``` + +## Platform-Specific Security + +### Linux + +**User namespace remapping:** +```json +// /etc/docker/daemon.json +{ + "userns-remap": "default" +} +``` + +Benefits: Root in container β†’ unprivileged on host + +**SELinux:** +```bash +# Enable SELinux for Docker +setenforce 1 + +# Run with SELinux labels +docker run --security-opt label=type:svirt_sandbox_file_t my-image + +# Volumes with SELinux +docker run -v /host/path:/container/path:z my-image +``` + +**AppArmor:** +```bash +# Check AppArmor status +aa-status + +# Run with AppArmor profile +docker run --security-opt apparmor=docker-default my-image +``` + +### Windows + +**Hyper-V isolation:** +```powershell +# More isolated than process isolation +docker run --isolation=hyperv my-image +``` + +**Windows Defender:** +- Ensure real-time protection enabled +- Configure exclusions carefully +- Scan images regularly + +### macOS + +**Docker Desktop security:** +- Keep Docker Desktop updated +- Enable "Use gRPC FUSE for file sharing" +- Limit file sharing to necessary paths +- Review resource allocation + +## Security Checklist + +**Image:** +- [ ] Based on official, minimal image +- [ ] Specific version tag (not `latest`) +- [ ] Scanned for vulnerabilities +- [ ] No secrets in layers +- [ ] Runs as non-root user +- [ ] Signed (Content Trust) + +**Build:** +- [ ] .dockerignore configured +- [ ] Multi-stage build (if applicable) +- [ ] Build secrets handled properly +- [ ] Build from trusted sources only + +**Runtime:** +- [ ] Non-root user +- [ ] Capabilities dropped +- [ ] Read-only filesystem (where possible) +- [ ] Security options set +- [ ] Resource limits configured +- [ ] Isolated network +- [ ] Minimal port exposure +- [ ] Secrets mounted securely + +**Operations:** +- [ ] CIS benchmark compliance +- [ ] Logging configured +- [ ] Monitoring in place +- [ ] Regular vulnerability scans +- [ ] Incident response plan +- [ ] Regular updates +- [ ] Audit logs enabled + +## Common Security Mistakes + +❌ **NEVER:** +- Run as root +- Use `--privileged` +- Mount Docker socket (`/var/run/docker.sock`) +- Hardcode secrets +- Use `latest` tag +- Skip vulnerability scanning +- Expose unnecessary ports +- Disable security features +- Ignore security updates +- Trust unverified images + +βœ… **ALWAYS:** +- Run as non-root +- Drop capabilities +- Scan for vulnerabilities +- Use secrets management +- Tag with specific versions +- Enable security options +- Apply least privilege +- Keep systems updated +- Monitor runtime behavior +- Use official images + +This security guide represents current best practices. Security threats evolve constantlyβ€”always check the latest Docker security documentation and CVE databases.