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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

services:
  app:
    volumes:
      - type: image
        source: mydata:latest
        target: /data
        read_only: true

3. Build Print:

# Debug complex build configurations
docker compose build --print > build-config.json

4. Config No-Env-Resolution:

# View raw config without environment variable substitution
docker compose config --no-env-resolution

5. Watch with Prune:

# Automatically prune unused resources during watch
docker compose watch --prune

6. Run with Quiet:

# Reduce output noise
docker compose run --quiet app npm test

BuildKit Updates (2025)

New Features

1. Git SHA-256 Support:

# Use SHA-256 based repositories
ADD https://github.com/user/repo#sha256:abc123... /src

2. Enhanced COPY/ADD --exclude:

# Now generally available (was labs-only)
COPY --exclude=*.test.js --exclude=*.md . /app

3. ADD --unpack with --chown:

# Extract and set ownership in one step
ADD --unpack=true --chown=appuser:appgroup archive.tar.gz /app

4. Git Query Parameters:

# Fine-grained Git clone control
ADD https://github.com/user/repo.git?depth=1&branch=main /src

5. Image Checksum Verification:

# Verify image integrity
FROM alpine:3.19@sha256:abc123...
# BuildKit verifies checksum automatically

Security Enhancements

1. Improved Frontend Verification:

# 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

• Docker AI — provide specific context, verify generated configs, combine with traditional security tools; never trust AI blindly for security-critical apps or skip manual review.
• Enhanced Container Isolation — enable for security-sensitive workloads, test compatibility, document socket access, apply least privilege; do not enable without testing or grant socket access casually.
• Modern Compose files — drop the version field, use new features (type: image volumes, watch improvements, --print, --quiet), and test under Compose v2.40+.

Migration, Troubleshooting & Adoption Timeline

For migration paths to Docker Desktop 4.38+, troubleshooting of new 2025 features (compose-bridge, hardened-mode quirks, BuildKit history), and the recommended feature-adoption timeline, see references/migration-troubleshooting-timeline.md.