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

• VirtioFS: Enable in Docker Desktop settings (faster)

• 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

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

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.