docker-admin

name	docker-admin
description	Build, manage, and configure Docker images and containers. Use when creating new sandbox environments, adding packages to existing images, or managing the Docker image catalog.

Docker Admin Skill (Cross-Platform Native Shell)

Use this skill when you need to create new Docker images, add packages to existing ones, manage containers, or troubleshoot Docker issues.

This is NOT for running code --- use the docker-sandbox skill for that.

---

Host System: {{os}}

The host OS may be:

• Windows → native PowerShell
• macOS → native bash/zsh
• Linux → native bash

Use the OS-native shell. Do NOT require PowerShell Core on macOS/Linux.

---

NAS Mount Behavior (Platform Aware)

Docker mount behavior differs by platform:

Windows (Docker Desktop + WSL2)

When mounting NAS paths on Windows, Docker Desktop may incorrectly resolve mounts when called from PowerShell.

Rule:

• Containers that need NAS access MUST be created via:

<!-- -->

wsl -u root docker run ...

This ensures Docker sees the correct filesystem context.

---

macOS / Linux

On macOS and Linux, Docker mounts work normally.

Use standard:

docker run ...

No WSL indirection is required.

---

Volume Mount Rules

When container NEEDS NAS access

Windows

wsl -u root docker run -d --name <n> -v "{{paths.sandbox}}:/nas" ubuntu:22.04 tail -f /dev/null
wsl -u root docker exec <n> ls -la /nas

macOS / Linux

docker run -d --name <n> -v "{{paths.sandbox}}:/nas" ubuntu:22.04 tail -f /dev/null
docker exec <n> ls -la /nas

---

When container does NOT need NAS

All platforms may use plain docker:

docker run --rm -v "{{paths.skills}}:/workspace" python-runtime-image python /workspace/script.py

(Use PowerShell syntax on Windows.)

---

NEVER Use

• Raw UNC paths in -v
• Mapped drive letters in -v
• Windows-only assumptions on macOS/Linux
• Plain docker run for NAS mounts on Windows

---

Verify NAS Mount

Always verify after container creation.

Windows

wsl -u root docker exec <n> ls -la /nas

If empty:

wsl -u root ls {{paths.sandbox}}
# If needed:
wsl -u root mount {{paths.sandbox}}

macOS / Linux

docker exec <n> ls -la /nas

---

Creating a New Image

1️⃣ Write the Dockerfile

Example:

FROM python:3.12-slim

RUN pip install --no-cache-dir \
    package-one \
    package-two \
    package-three

WORKDIR /workspace

Key rules:

• Always use --no-cache-dir with pip
• Prefer -slim base images
• Always set WORKDIR /workspace
• Install system packages BEFORE pip when needed

Example with apt:

FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libmagic1 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir some-package

WORKDIR /workspace

---

2️⃣ Build the Image

All platforms:

docker build -t <image-name> <path-to-directory-containing-Dockerfile>

Naming convention:

• Use descriptive names for images
• lowercase
• dashes only

---

3️⃣ Verify the Image

docker run --rm <image-name> python -c "import package_one; print('OK')"

---

Extending an Existing Image

FROM python-runtime-image

RUN pip install --no-cache-dir \
    new-package-one \
    new-package-two

WORKDIR /workspace

---

Long-Running Containers

Windows

wsl -u root docker run -d --name git-container -v "{{paths.sandbox}}:/nas" ubuntu:22.04 tail -f /dev/null
wsl -u root docker exec git-container ls -la /nas

macOS / Linux

docker run -d --name git-container -v "{{paths.sandbox}}:/nas" ubuntu:22.04 tail -f /dev/null
docker exec git-container ls -la /nas

---

Managing Images

List images

docker images --filter "reference=*" --format "{{.Repository}}:{{.Tag}} ({{.Size}}) Created: {{.CreatedSince}}"

Remove image

docker rmi <image-name>

Check installed packages

docker run --rm python-runtime-image pip list
docker run --rm node-runtime-image npm list -g

Cleanup

docker system prune -f

---

Troubleshooting

Volume mount empty (Windows)

• Ensure use of wsl -u root docker run
• Verify WSL mount active
• Never use UNC or mapped drives

Volume mount empty (macOS/Linux)

• Verify path exists on host
• Verify Docker has filesystem permissions

Build fails on pip install

• Check package spelling
• Install required system libraries first

Image too large

• Use -slim base
• Chain RUN commands
• Use --no-install-recommends
• Clean apt lists
• Use --no-cache-dir

---

Rules

• NAS-mounted containers on Windows MUST use wsl -u root docker run
• macOS/Linux use normal docker run
• Use clear, descriptive image names
• Always use --no-cache-dir with pip
• Prefer -slim base images
• Always verify NAS mounts
• Never store credentials in images
• Never use --privileged
• Never use UNC or mapped drives in -v
• Report final image name and size after building

---

Platform Summary

Component Windows macOS Linux

---

Shell PowerShell bash/zsh bash NAS mount via WSL native native Docker run wsl wrapper (NAS) native native Verification wsl docker exec docker exec docker exec Build docker build docker build docker build