Docker Learning Journey

An interactive, progressive Docker learning guide designed for Python and FastAPI developers. Learn by doing with practical exercises and real-world examples.

What This Skill Does

• Teaches Docker concepts progressively (basics → intermediate → production)
• Connects Docker concepts to Python/FastAPI knowledge you already have
• Provides hands-on exercises at each level
• Offers quick command references with explanations
• Guides containerization of FastAPI applications

What This Skill Does NOT Do

• Cover Kubernetes (that's a separate journey)
• Handle cloud-specific deployments (AWS ECS, GCP Cloud Run)
• Replace official Docker documentation for edge cases

---

Before Starting

Assess where you are:

| Level | You Can... | Start At | |-------|------------|----------| | Beginner | Haven't used Docker | Module 1 | | Basic | Run containers, pull images | Module 2 | | Intermediate | Write Dockerfiles, use compose | Module 3 | | Advanced | Multi-stage builds, optimization | Module 4 |

---

Learning Modules

Module 1: Docker Fundamentals

Goal: Understand what Docker is and run your first container

Key Concepts:

Image      = Blueprint/Recipe (like a Python class)
Container  = Running instance (like a Python object)
Registry   = Image storage (like PyPI for packages)

Your First Commands:

# 1. Check Docker is installed
docker --version

# 2. Pull an image (download the blueprint)
docker pull python:3.12-slim

# 3. Run a container (create an instance)
docker run -it python:3.12-slim python
# You're now inside a Python container! Type exit() to leave

# 4. See what's running
docker ps        # Running containers
docker ps -a     # All containers (including stopped)

# 5. See downloaded images
docker images

Python Analogy:

# This is like Docker:
class PythonEnvironment:        # Image
    def __init__(self):
        self.python = "3.12"
        self.packages = []

env1 = PythonEnvironment()      # Container 1
env2 = PythonEnvironment()      # Container 2 (isolated!)

Exercise: See assets/exercises/01-first-container.md

---

Module 2: Building Images with Dockerfile

Goal: Create your own images with Dockerfile

Key Concept: Dockerfile = Recipe with steps

# Every Dockerfile starts with a base image
FROM python:3.12-slim

# Set working directory (like cd)
WORKDIR /app

# Copy files from your computer into the image
COPY requirements.txt .

# Run commands (install dependencies)
RUN pip install -r requirements.txt

# Copy your application code
COPY . .

# Default command when container starts
CMD ["python", "main.py"]

Layer Concept (Important!):

┌─────────────────────────┐
│ CMD ["python", "main.py"] │  ← Layer 5 (your command)
├─────────────────────────┤
│ COPY . .                  │  ← Layer 4 (your code)
├─────────────────────────┤
│ RUN pip install...        │  ← Layer 3 (dependencies)
├─────────────────────────┤
│ COPY requirements.txt     │  ← Layer 2 (requirements file)
├─────────────────────────┤
│ FROM python:3.12-slim     │  ← Layer 1 (base image)
└─────────────────────────┘

Each layer is CACHED! Change order matters for speed.

Build Commands:

# Build an image from Dockerfile
docker build -t myapp:v1 .

# -t = tag (name:version)
# .  = build context (current directory)

# Run your new image
docker run myapp:v1

Exercise: See assets/exercises/02-first-dockerfile.md

---

Module 3: Docker Compose (Multi-Container Apps)

Goal: Run multiple containers together (FastAPI + Database)

Key Concept: Compose = Orchestra conductor for containers

# docker-compose.yml
services:
  api:                          # Your FastAPI app
    build: .
    ports:
      - "8000:8000"             # host:container
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    depends_on:
      - db

  db:                           # PostgreSQL database
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=app
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:                # Persist data between restarts

Compose Commands:

# Start all services
docker compose up

# Start in background (detached)
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f api

# Rebuild after code changes
docker compose up --build

Exercise: See assets/exercises/03-compose-fastapi.md

---

Module 4: Production Patterns

Goal: Build optimized, secure, production-ready images

Multi-Stage Builds (The Key Technique):

# Stage 1: Builder (temporary, has build tools)
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev

# Stage 2: Runtime (final, minimal)
FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY ./app ./app
ENV PATH="/app/.venv/bin:$PATH"
CMD ["fastapi", "run", "app/main.py", "--port", "80"]

Why Multi-Stage?

Builder Stage: 400MB (has uv, build tools)
         ↓
    Copies only .venv
         ↓
Runtime Stage: 150MB (minimal, secure)

Production Checklist:

• [ ] Multi-stage build (small image)
• [ ] Non-root user (security)
• [ ] Health check (monitoring)
• [ ] .dockerignore (exclude unnecessary files)
• [ ] No secrets in image (use env vars)

Exercise: See assets/exercises/04-production-build.md

---

Quick Reference

Essential Commands

| Task | Command | |------|---------| | Pull image | docker pull image:tag | | Run container | docker run -d -p 8000:80 image | | List running | docker ps | | List all | docker ps -a | | Stop container | docker stop <id> | | Remove container | docker rm <id> | | List images | docker images | | Build image | docker build -t name:tag . | | Remove image | docker rmi image:tag | | View logs | docker logs <id> | | Shell into | docker exec -it <id> /bin/bash |

Compose Commands

| Task | Command | |------|---------| | Start services | docker compose up | | Start detached | docker compose up -d | | Stop services | docker compose down | | Rebuild | docker compose up --build | | View logs | docker compose logs -f | | Run command | docker compose exec api bash |

Port Mapping Explained

-p 8000:80
   │    │
   │    └── Container port (inside)
   └─────── Host port (your computer)

Access at: http://localhost:8000

---

Common Errors & Solutions

| Error | Cause | Solution | |-------|-------|----------| | "port already in use" | Another process on that port | Change host port or stop other process | | "image not found" | Typo or not pulled | docker pull image:tag | | "permission denied" | Docker daemon not running | Start Docker Desktop | | "no space left" | Docker cache full | docker system prune | | "connection refused" | Container not ready | Add health check, use depends_on |

---

Python Developer's Mental Model

| Python | Docker | |--------|--------| | pip install | docker pull | | requirements.txt | Dockerfile's RUN pip install | | venv | Container isolation | | python main.py | docker run | | pip freeze | docker images | | Multiple projects | Multiple containers | | .gitignore | .dockerignore |

---

Learning Path Checklist

Week 1: Foundations

• [ ] Install Docker Desktop
• [ ] Run hello-world container
• [ ] Pull and run Python image
• [ ] Understand images vs containers
• [ ] Complete Exercise 01

Week 2: Building

• [ ] Write first Dockerfile
• [ ] Build custom image
• [ ] Understand layers and caching
• [ ] Complete Exercise 02

Week 3: Composing

• [ ] Write docker-compose.yml
• [ ] Run FastAPI + PostgreSQL
• [ ] Understand volumes and networks
• [ ] Complete Exercise 03

Week 4: Production

• [ ] Multi-stage Dockerfile
• [ ] Optimize image size
• [ ] Add security practices
• [ ] Complete Exercise 04

---

Reference Files

| File | When to Read | |------|--------------| | references/01-core-concepts.md | Deep dive into Docker architecture | | references/02-dockerfile-reference.md | All Dockerfile instructions | | references/03-compose-reference.md | Docker Compose file format | | references/04-fastapi-docker.md | FastAPI-specific patterns | | references/05-troubleshooting.md | Common issues and fixes |

Exercises

| Exercise | Level | Goal | |----------|-------|------| | assets/exercises/01-first-container.md | Beginner | Run Python in container | | assets/exercises/02-first-dockerfile.md | Beginner | Build custom image | | assets/exercises/03-compose-fastapi.md | Intermediate | Full stack app | | assets/exercises/04-production-build.md | Advanced | Optimized deployment |

Cheatsheets

| File | Contents | |------|----------| | assets/cheatsheets/commands.md | All Docker commands | | assets/cheatsheets/dockerfile.md | Dockerfile syntax | | assets/cheatsheets/compose.md | Compose file syntax |