Docker Workflows Skill

When to Activate

Activate this skill when:

• Creating Dockerfiles for applications

• Setting up docker-compose environments

• Containerizing Python/UV projects

• Configuring multi-stage builds

• Managing container secrets

Quick Commands

Build image

docker build -t my-app:latest .

Run container

docker run -d -p 8000:8000 --name my-app my-app:latest

View logs

docker logs -f my-app

Execute in container

docker exec -it my-app bash

Stop and remove

docker stop my-app && docker rm my-app

Clean up

docker system prune -a

Basic Dockerfile (Python/UV)

FROM python:3.11-slim

WORKDIR /app

Install UV

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

Copy dependency files (layer caching)

COPY pyproject.toml uv.lock ./

Install dependencies

RUN uv sync --frozen --no-dev

Copy application

COPY . .

EXPOSE 8000

CMD ["uv", "run", "python", "main.py"]

Multi-Stage Build (Production)

Stage 1: Builder

FROM python:3.11-slim AS builder

WORKDIR /app COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev

COPY . .

Stage 2: Runtime

FROM python:3.11-slim

WORKDIR /app

Create non-root user

RUN useradd -m -u 1000 appuser && chown appuser:appuser /app

Copy from builder

COPY --from=builder /app/.venv /app/.venv COPY --from=builder /app /app

USER appuser

ENV PATH="/app/.venv/bin:$PATH"

EXPOSE 8000 CMD ["python", "main.py"]

.dockerignore

pycache/ *.pyc .git/ .env .venv/ venv/ *.log .DS_Store .pytest_cache/ tests/ docs/ *.md

Docker Compose (App + Database)

version: '3.8'

services: app: build: . ports: - "8000:8000" environment: - DATABASE_URL=postgresql://user:password@db:5432/myapp depends_on: - db volumes: - ./app:/app # Development: live reload

db: image: postgres:15-alpine environment: - POSTGRES_USER=user - POSTGRES_PASSWORD=password - POSTGRES_DB=myapp volumes: - postgres_data:/var/lib/postgresql/data ports: - "5432:5432"

volumes: postgres_data:

Compose Commands

Start all services

docker-compose up -d

View logs

docker-compose logs -f app

Stop services

docker-compose down

Rebuild and restart

docker-compose up -d --build

Run command in service

docker-compose exec app bash

Remove volumes (deletes data!)

docker-compose down -v

Layer Caching Best Practice

Good: Dependencies cached separately

COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev COPY . .

Bad: Cache invalidated on every code change

COPY . . RUN uv sync --frozen --no-dev

Security Essentials

Use official slim images

FROM python:3.11-slim

Run as non-root

RUN useradd -m -u 1000 appuser USER appuser

Don't include secrets in images

Use runtime environment variables instead

Runtime Secrets

Pass via environment

docker run -e API_KEY=secret my-app

Use env file

docker run --env-file .env.production my-app

With compose

services: app: env_file: - .env.production

Volume Types

Named volume (data persistence)

docker run -v postgres_data:/var/lib/postgresql/data postgres

Bind mount (development)

docker run -v $(pwd)/app:/app my-app

Debugging

Interactive shell

docker exec -it container_name bash

Real-time logs

docker logs -f --tail 100 container_name

Inspect configuration

docker inspect container_name

Resource usage

docker stats container_name

Copy files

docker cp container_name:/app/logs ./logs

Common Issues

Container exits immediately

docker logs container_name # Check for errors docker run -it app:v1 bash # Debug interactively

Can't connect to container

docker ps # Check port mapping docker inspect container_name # Check network config

Out of disk space

docker system df # Check usage docker system prune -a # Clean everything

Related Resources

See AgentUsage/docker_guide.md for complete documentation including:

• Advanced multi-stage patterns

• Docker Compose variations

• Production optimization

• CI/CD integration