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:

code

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

Your First Commands:

bash

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

python

# 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

dockerfile

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

code

┌─────────────────────────┐
│ 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:

bash

# 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

yaml

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

bash

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

dockerfile

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

code

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

code

-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

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