zhongwei/gh-josiahsiegel-claude-code-marketplace-plugins-docker-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:02 +08:00
commit a0a3623551
9 changed files with 4121 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

329
agents/docker-expert.md Normal file
View File

@@ -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.

65
plugin.lock.json Normal file
View File

@@ -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": []
}
}

753
skills/docker-2025-features.md Normal file
View File

@@ -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.

656
skills/docker-best-practices.md Normal file
View File

@@ -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.

543
skills/docker-git-bash-guide.md Normal file
View File

@@ -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.

753
skills/docker-platform-guide.md Normal file
View File

@@ -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.

1004
skills/docker-security-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff