docker-platform-guide（Docker platform 指南）

🚨 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:

# 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):

{
  "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:

# Enable in daemon.json
{
  "userns-remap": "default"
}

# Restart Docker
sudo systemctl restart docker

# Result: root in container = unprivileged user on host

SELinux Integration

# 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

# 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

# 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

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

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

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

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

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:

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

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

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "20GB"
    }
  },
  "experimental": false,
  "features": {
    "buildkit": true
  }
}

macOS File Permissions

# 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

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

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

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

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

# 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):

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

# 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):

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

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

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

# Git configuration
git config --global core.autocrlf input

# Or per-repo (.gitattributes)
* text=auto
*.sh text eol=lf
*.bat text eol=crlf

# 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

# 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

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

# 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

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

# 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

Cross-Platform Best Practices

Multi-Platform Images

# 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

# 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

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

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