feat: add Module 09 — Docker & Deployment curriculum

Five projects covering Dockerfile basics, multi-stage builds, docker-compose
with PostgreSQL, GitHub Actions CI pipelines, and production configuration
(env vars, health checks, non-root users, structured logging).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

projects/modules/09-docker-deployment/01-first-dockerfile/Dockerfile

@@ -0,0 +1,92 @@
+# ============================================================================
+# Dockerfile — First Dockerfile
+# ============================================================================
+# A Dockerfile is a recipe for building a container image. Each instruction
+# adds a layer to the image. Docker caches layers, so unchanged layers are
+# reused on subsequent builds (this makes rebuilds fast).
+#
+# Build this image:
+#   docker build -t first-dockerfile .
+#
+# Run a container from the image:
+#   docker run -p 8000:8000 first-dockerfile
+# ============================================================================
+
+# --------------------------------------------------------------------------
+# FROM — choose the base image.
+# Every Docker image starts from a parent image. python:3.12-slim is an
+# official Python image based on Debian with unnecessary packages removed.
+# "slim" means it is smaller than the full image (~150 MB vs ~900 MB).
+#
+# Why not python:3.12 (full)?   — Too large. Includes compilers and tools
+#                                  you do not need at runtime.
+# Why not python:3.12-alpine?   — Alpine uses musl libc instead of glibc.
+#                                  Some Python packages (numpy, pandas) do
+#                                  not have pre-built wheels for Alpine and
+#                                  require compiling from source, which is
+#                                  slow and error-prone.
+# --------------------------------------------------------------------------
+FROM python:3.12-slim
+
+# --------------------------------------------------------------------------
+# WORKDIR — set the working directory inside the container.
+# All subsequent commands (COPY, RUN, CMD) execute relative to this path.
+# If the directory does not exist, Docker creates it.
+# This is like running "cd /app" at the start of a shell session.
+# --------------------------------------------------------------------------
+WORKDIR /app
+
+# --------------------------------------------------------------------------
+# COPY requirements.txt first (before copying the rest of the code).
+# Docker caches each layer. If requirements.txt has not changed, Docker
+# reuses the cached pip install layer and skips the slow download step.
+# This is called "layer caching" and it makes rebuilds much faster.
+# --------------------------------------------------------------------------
+COPY requirements.txt .
+
+# --------------------------------------------------------------------------
+# RUN — execute a command during the build.
+# pip install reads requirements.txt and installs the listed packages.
+#
+# --no-cache-dir  — do not store pip's download cache inside the image.
+#                   The cache wastes space because you will never pip install
+#                   again inside this image.
+# --------------------------------------------------------------------------
+RUN pip install --no-cache-dir -r requirements.txt
+
+# --------------------------------------------------------------------------
+# COPY . . — copy the rest of your application code into the image.
+# The first "." is the source (your project directory on the host).
+# The second "." is the destination (/app inside the container, because
+# WORKDIR is set to /app).
+#
+# This step is separate from COPY requirements.txt so that code changes
+# do not invalidate the pip install cache layer.
+# --------------------------------------------------------------------------
+COPY . .
+
+# --------------------------------------------------------------------------
+# EXPOSE — document which port the container listens on.
+# This does NOT actually publish the port. It is metadata for anyone
+# reading the Dockerfile. The actual port mapping happens at runtime
+# with "docker run -p 8000:8000".
+# --------------------------------------------------------------------------
+EXPOSE 8000
+
+# --------------------------------------------------------------------------
+# CMD — the default command to run when the container starts.
+# This starts uvicorn, which serves the FastAPI application.
+#
+# --host 0.0.0.0  — listen on all network interfaces inside the container.
+#                   Without this, the server only listens on 127.0.0.1
+#                   (localhost inside the container), which is unreachable
+#                   from the host machine.
+# --port 8000     — match the EXPOSE declaration above.
+#
+# CMD uses the "exec form" (JSON array) instead of the "shell form"
+# (plain string). The exec form runs uvicorn as PID 1, which means it
+# receives shutdown signals (SIGTERM) directly. The shell form wraps the
+# command in /bin/sh, which can swallow signals and prevent graceful
+# shutdown.
+# --------------------------------------------------------------------------
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

projects/modules/09-docker-deployment/01-first-dockerfile/README.md

@@ -0,0 +1,110 @@
+# Module 09 / Project 01 — First Dockerfile
+
+Home: [README](../../../../README.md)
+
+## Focus
+
+Writing a Dockerfile, building an image, and running a container.
+
+## Why this project exists
+
+Docker packages your application and all its dependencies into a single image that runs the same way on every machine. No more "it works on my laptop" problems. This project teaches you the fundamental Docker workflow: write a Dockerfile, build an image, run a container. Every deployment pipeline in the industry starts here.
+
+## Run
+
+### Without Docker (verify the app works locally first)
+
+```bash
+cd projects/modules/09-docker-deployment/01-first-dockerfile
+python app.py
+```
+
+Visit http://127.0.0.1:8000 to confirm it works, then stop the server with `Ctrl+C`.
+
+### With Docker
+
+**Step 1 — Build the image.** This reads the Dockerfile and creates an image named `first-dockerfile`:
+
+```bash
+docker build -t first-dockerfile .
+```
+
+You will see Docker execute each instruction. The first build downloads the base image and installs dependencies (slow). Subsequent builds reuse cached layers (fast).
+
+**Step 2 — Run a container from the image:**
+
+```bash
+docker run -p 8000:8000 first-dockerfile
+```
+
+The `-p 8000:8000` flag maps port 8000 on your machine to port 8000 inside the container.
+
+**Step 3 — Visit your app:**
+
+- http://127.0.0.1:8000 — root endpoint
+- http://127.0.0.1:8000/health — health check
+- http://127.0.0.1:8000/docs — interactive API docs
+
+**Step 4 — Stop the container** with `Ctrl+C`.
+
+### Useful Docker commands
+
+```bash
+docker images                    # list all images on your machine
+docker ps                        # list running containers
+docker ps -a                     # list all containers (including stopped)
+docker rm <container_id>         # remove a stopped container
+docker rmi first-dockerfile      # remove the image
+```
+
+## Expected output
+
+Visiting http://127.0.0.1:8000 returns:
+
+```json
+{"message": "Hello from Docker!", "version": "1.0.0"}
+```
+
+Visiting http://127.0.0.1:8000/health returns:
+
+```json
+{"status": "healthy"}
+```
+
+## Alter it
+
+1. Add a `GET /info` endpoint that returns `{"container": True, "python_version": "3.12"}`. Rebuild the image and verify.
+2. Change the `CMD` in the Dockerfile to run on port 9000. Update the `EXPOSE` instruction and the `docker run` command to match.
+3. Add a `--name my-app` flag to `docker run` so you can refer to the container by name instead of ID.
+
+## Break it
+
+1. Remove the `COPY requirements.txt .` and `RUN pip install` lines from the Dockerfile. Rebuild and try to run. What error do you get?
+2. Change `--host 0.0.0.0` to `--host 127.0.0.1` in the CMD instruction. Rebuild and run. Can you reach the app from your browser? Why not?
+3. Swap the order of `COPY requirements.txt .` and `COPY . .` so all files are copied in one step. Does it still work? What happens to build caching when you change only `app.py`?
+
+## Fix it
+
+1. Restore the `COPY requirements.txt` and `RUN pip install` lines. The app cannot start without its dependencies installed in the image.
+2. Change the host back to `0.0.0.0`. Inside a container, `127.0.0.1` only accepts connections from inside the container itself, not from the host machine.
+3. Separate the two COPY steps again. With a single COPY, every code change invalidates the pip install cache and forces a slow reinstall.
+
+## Explain it
+
+1. What is the difference between a Docker image and a Docker container?
+2. Why does the Dockerfile copy `requirements.txt` and run `pip install` before copying the rest of the code?
+3. What does `-p 8000:8000` mean in the `docker run` command? What happens if you use `-p 3000:8000`?
+4. Why does the CMD use `--host 0.0.0.0` instead of `--host 127.0.0.1`?
+
+## Mastery check
+
+You can move on when you can:
+
+- write a Dockerfile from scratch without looking at this one,
+- build an image and run a container with port mapping,
+- explain why layer order matters for build caching,
+- describe the difference between EXPOSE and `-p`.
+
+## Next
+
+Continue to [02-multi-stage-build](../02-multi-stage-build/).

projects/modules/09-docker-deployment/01-first-dockerfile/app.py

@@ -0,0 +1,69 @@
+# ============================================================================
+# Project 01 — First Dockerfile
+# ============================================================================
+# A minimal FastAPI application designed to run inside a Docker container.
+# This is the same kind of app you built in Module 04, but now you will
+# package it into a container image so it runs identically on any machine.
+#
+# Run locally (without Docker):
+#   python app.py
+#
+# Run with Docker (after building the image):
+#   docker run -p 8000:8000 first-dockerfile
+#
+# Then visit:
+#   http://127.0.0.1:8000        — root endpoint
+#   http://127.0.0.1:8000/health — health check
+#   http://127.0.0.1:8000/docs   — interactive API documentation
+# ============================================================================
+
+from fastapi import FastAPI
+
+# ----------------------------------------------------------------------------
+# Create the FastAPI application instance.
+# The title and version appear in the auto-generated /docs page.
+# ----------------------------------------------------------------------------
+app = FastAPI(
+    title="First Dockerfile App",
+    version="1.0.0",
+)
+
+
+# ----------------------------------------------------------------------------
+# Route 1: GET /
+# A simple root endpoint that confirms the app is running.
+# When this response comes from a Docker container, you know the entire
+# build-and-run pipeline is working.
+# ----------------------------------------------------------------------------
+@app.get("/")
+def read_root():
+    """Return a welcome message confirming the app is running."""
+    return {"message": "Hello from Docker!", "version": "1.0.0"}
+
+
+# ----------------------------------------------------------------------------
+# Route 2: GET /health
+# Health check endpoints are essential in containerized environments.
+# Orchestrators like Docker Swarm and Kubernetes ping this endpoint to
+# decide whether the container is healthy. If it stops responding, the
+# orchestrator restarts the container automatically.
+# ----------------------------------------------------------------------------
+@app.get("/health")
+def health_check():
+    """Health check endpoint for container orchestrators."""
+    return {"status": "healthy"}
+
+
+# ----------------------------------------------------------------------------
+# Run the server when executed directly (local development without Docker).
+#
+# Inside a Docker container, you run uvicorn via the CMD instruction in the
+# Dockerfile instead of using this block. The host is set to "0.0.0.0" so
+# the server accepts connections from outside the container. Using
+# "127.0.0.1" inside a container would make the app unreachable because
+# the container has its own network namespace.
+# ----------------------------------------------------------------------------
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run("app:app", host="0.0.0.0", port=8000, reload=True)

projects/modules/09-docker-deployment/01-first-dockerfile/notes.md

@@ -0,0 +1,10 @@
+# Notes — First Dockerfile
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/09-docker-deployment/01-first-dockerfile/requirements.txt

@@ -0,0 +1,6 @@
+# Dependencies for the First Dockerfile project.
+# This file is copied into the Docker image and used by pip install.
+# Keeping it separate from the module-level requirements.txt means the
+# Docker image only installs what this specific app needs.
+fastapi>=0.109
+uvicorn[standard]>=0.27

projects/modules/09-docker-deployment/02-multi-stage-build/.dockerignore

@@ -0,0 +1,65 @@
+# ============================================================================
+# .dockerignore — Files to exclude from the Docker build context
+# ============================================================================
+# When you run "docker build", Docker sends your entire project directory
+# (the "build context") to the Docker daemon. The .dockerignore file tells
+# Docker which files to skip. This:
+#
+# 1. Reduces build context size (faster builds).
+# 2. Prevents sensitive or unnecessary files from ending up in the image.
+# 3. Avoids invalidating Docker layer caches with irrelevant file changes.
+# ============================================================================
+
+# --------------------------------------------------------------------------
+# Python bytecode — generated at runtime, not needed in the image.
+# __pycache__ directories contain .pyc files that Python creates when it
+# imports a module. They are platform-specific and should be regenerated
+# inside the container.
+# --------------------------------------------------------------------------
+__pycache__/
+*.pyc
+*.pyo
+
+# --------------------------------------------------------------------------
+# Virtual environment — the Docker image builds its own.
+# Including a local .venv would waste hundreds of megabytes and the packages
+# might not be compatible with the container's operating system.
+# --------------------------------------------------------------------------
+.venv/
+venv/
+env/
+
+# --------------------------------------------------------------------------
+# Git history — not needed at runtime and can be very large.
+# --------------------------------------------------------------------------
+.git/
+.gitignore
+
+# --------------------------------------------------------------------------
+# IDE and editor files — configuration specific to your machine.
+# --------------------------------------------------------------------------
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# --------------------------------------------------------------------------
+# Data and log files — often large and environment-specific.
+# --------------------------------------------------------------------------
+data/
+*.log
+
+# --------------------------------------------------------------------------
+# Docker-related files — no need to copy Dockerfiles into the image.
+# --------------------------------------------------------------------------
+Dockerfile
+Dockerfile.*
+docker-compose*.yml
+.dockerignore
+
+# --------------------------------------------------------------------------
+# Documentation — not needed in the runtime image.
+# --------------------------------------------------------------------------
+README.md
+notes.md
+*.md