"It works on my machine." Every developer has said it — usually right before the same app breaks on a server, because something there is different: another Python version, a library missing, a file that never got copied.
Docker ends that argument. You pack the app together with everything it needs into one box — an image — and the box runs the same everywhere. In this post we dockerize a FastAPI app — from a plain Dockerfile to a running container — then pack it properly: the careless first try weighs 1.65 GB; the proper pack weighs 198 MB. Same app. Smaller box.
Get the code: all files from this post are free in the companion repo —
https://github.com/sajjad037/visual-studio-learn-code/tree/main/topic-14-docker-fastapi
The map
Four stops, and everything below is one of them:
- The recipe — a
Dockerfile: a short text file that describes the box. - The packed box — Docker reads the recipe and builds an image: your app, frozen together with Python and every library it needs.
- The running box — start the image and it becomes a container: your app, running, sealed off from the machine.
- The proof — we ask the app a question over the network, and it answers.
Step 1 — The app: a tiny notes API
Our app is deliberately small — one file, main.py, with three endpoints (an endpoint is one address the app answers on):
-
GET /health— answers "I am alive". Remember this one; Docker itself will use it later. -
GET /notes— lists the notes. -
POST /notes— adds a note.
Here is the whole file, to copy:
"""Tiny notes API — the demo app we dockerize in Topic #14. Three endpoints are enough to prove a container works: GET /health -> {"status": "ok"} (used by the Docker HEALTHCHECK) GET /notes -> list of notes POST /notes -> add a note {"text": "..."} """ from fastapi import FastAPI from pydantic import BaseModel app = FastAPI(title="Notes API") notes: list[dict] = [{"id": 1, "text": "Ship it in a container"}] class NoteIn(BaseModel): text: str @app.get("/health") def health(): return {"status": "ok"} @app.get("/notes") def list_notes(): return notes @app.post("/notes", status_code=201) def add_note(note: NoteIn): new = {"id": len(notes) + 1, "text": note.text} notes.append(new) return new And requirements.txt — the three libraries, pinned:
fastapi==0.115.6 uvicorn==0.34.0 pydantic==2.10.4 Step 2 — The first recipe: the naive Dockerfile
"Naive" just means the obvious first try — five working lines:
# NAIVE FIRST DRAFT — it works, but wait for the size. FROM python:3.12 WORKDIR /app COPY . . RUN pip install -r requirements.txt CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] Line by line:
-
FROM python:3.12— start from a ready-made box that already has Python inside. -
WORKDIR /app— the folder the app lives in, inside the box. -
COPY . .— copy everything from the project folder into the box. -
RUN pip install— install the libraries listed inrequirements.txt. -
CMD— the command that starts the app when the box runs.
Step 3 — Build it and run it
One command builds the image, following the recipe line by line (the first build also downloads that Python box, so it takes a while):
docker build -f Dockerfile.naive -t notes-api:naive . Now start it. docker run takes the packed box and starts it as a running container. A port is a numbered door into the app — -p 8000:8000 connects door 8000 on the outside to door 8000 inside:
docker run -d --name notes -p 8000:8000 notes-api:naive And now the proof — we ask the app, over the network:
curl http://localhost:8000/health # {"status":"ok"} curl http://localhost:8000/notes # [{"id":1,"text":"Ship it in a container"}] curl -X POST http://localhost:8000/notes -H "Content-Type: application/json" -d '{"text":"Docker works"}' # {"id":2,"text":"Docker works"} It works — exactly as it did on my machine. But look at the price tag:
docker images 1.65 GB — for a notes app of about forty lines. The full Python box carries an entire operating system, compilers, and tools we never asked for — and all of it travels to every server, every deploy.
Step 4 — Pack properly: slim base, two stages
The new recipe fixes the weight in four moves:
# ---- Stage 1: install dependencies into a clean prefix ---- FROM python:3.12-slim AS builder WORKDIR /build COPY requirements.txt . RUN pip install --no-cache-dir --prefix=/install -r requirements.txt # ---- Stage 2: the small runtime image that actually ships ---- FROM python:3.12-slim RUN useradd --create-home appuser WORKDIR /app COPY --from=builder /install /usr/local COPY --chown=appuser:appuser main.py . USER appuser EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=3s \ CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] - Slim base.
python:3.12-slimis the same Python on a diet: 179 MB instead of 1.62 GB. - Two stages — the big move. Stage 1 (
builder) installs the libraries into one clean folder (/install). Stage 2 starts again from the fresh slim box and copies in only that finished folder — the builder's tools and mess never enter the box we ship. -
.dockerignoreguards the copy. It lists what stays out of the build context: caches (__pycache__/,*.pyc), git history (.git/), virtualenvs (.venv/), and the recipes themselves. The whole file:
__pycache__/ *.pyc .git/ .venv/ Dockerfile* docker-compose.yml README.md - Non-root user. The naive box ran everything as root, the all-powerful account. This box runs as an ordinary user (
USER appuser) — if someone breaks the app, they land in a much smaller room. One catch, learned while making the video: copied files must belong to that user — that is why theCOPYformain.pynames its owner with--chown. - Health check.
HEALTHCHECKmakes Docker ask the health endpoint every thirty seconds — still alive? — and report the answer beside the container's name.
First, stop the naive container — docker rm -f notes — so its name and port 8000 are free again. Then rebuild and line the two boxes up side by side:
docker build -t notes-api:slim . docker images Naive: 1.65 GB. Slim: 198 MB — more than eight times smaller. Same app, same answers: we ran the same three questions against the slim container — health ok, notes listed, note added — and Docker's own status now adds one word: healthy.
Step 5 — The everyday workflow: docker compose
Day to day, you will not type the long commands. This compose file — six lines — describes the service once: build it here, call the image this, connect port 8000:
services: notes: build: . image: notes-api:slim ports: - "8000:8000" Then one command builds and starts everything, and one command brings it all down:
docker compose up -d docker compose ps curl http://localhost:8000/health docker compose down Step 6 — Scan the box before you ship it
One last check before we call this box production-shaped: is anything inside it known to be dangerous? Trivy is a free scanner — it compares every package in the image against the public lists of known holes:
trivy image --severity HIGH,CRITICAL notes-api:slim trivy image --severity HIGH,CRITICAL notes-api:naive The honest result, measured on the recording machine:
- Slim image: 51 serious findings (high or critical) — 48 in operating-system packages, 3 in a Python library.
- Naive image: 505 — 502 in operating-system packages, and the same 3 in the Python library.
Two caveats, in plain words. A scan only finds holes that are already known and listed. And shrinking the box does not fix your own libraries: both images carry the same three findings in one Python library (Starlette — the scanner names the fixed version). Those you fix by updating the library. Smaller box, shorter list, less to patch — that is the real win.
Save this — the small-box checklist
- Slim base — 179 MB, not 1.62 GB.
- Two stages — build in one stage, ship only the result.
-
.dockerignore— keep the junk out. - Non-root user — a smaller room if something breaks in.
- Health check — Docker keeps asking "still alive?"
Same app. Smaller box.
Your turn: your image is over a gigabyte — which two changes shrink it the most, and why? Tell me in the comments; I read every one.
Everything in this post was run for real on Docker 29.1.3 (Ubuntu 24.04) on 2026-11-18; image sizes and scan counts are the measured results of that run. Your numbers will be close, not identical — base images and vulnerability lists change over time.












