Docker for ML

Work inside churn-repo from 4.1 and 4.2, with models/churn_pipeline.joblib trained.

Honest setup note. Docker Desktop (Windows/macOS) or Docker Engine (Linux) needs an install and admin rights. Follow the official guide at docs.docker.com/get-docker the 0.1 way — official source, defaults, then verify with docker --version and docker run hello-world. On a locked-down college or office laptop you may not get admin, and that is fine: every command below shows its real output. Read along, do the read-along variant of each exercise, and let the checks test your reading and diagnosis. In 4.6, GitHub Actions builds this exact image for you in the cloud, and you catch up hands-on there.

Step 1 — the Dockerfile, line by line. One new file at the repo root:

# Dockerfile — the churn service, sealed in a box
FROM python:3.12-slim

WORKDIR /app

# requirements first — the slow layer, cached until the pins change
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# code second — changes daily, rebuilds in seconds
COPY config.py .
COPY src/ src/
COPY app/ app/

# the model, shipped deliberately (see .dockerignore)
COPY models/churn_pipeline.joblib models/churn_pipeline.joblib

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Read it top to bottom. FROM python:3.12-slim starts from a base that is itself an image — a trimmed Debian with Python 3.12 preinstalled, about 125 MB against the 1.02 GB full variant. WORKDIR /app creates a folder inside the image and makes every later line run there. Then the ordering trick: COPY requirements.txt . brings in only the pins, and RUN pip install executes at build time, baking the packages into the image itself — no venv, no activation, because the box IS the environment. Code arrives after, in its own layers. The model line names one exact file on both sides, so a reviewer can see precisely what ships. EXPOSE 8000 is documentation for humans and tools; CMD is the one command every container from this image runs at start. Note --host 0.0.0.0 — inside a container, binding 127.0.0.1 means talking to yourself, and nobody outside can connect. That single flag is the difference between a service and WR-099.

Step 2 — .dockerignore, the bouncer at the build. Second new file at the root:

# .dockerignore — what never enters the build
.venv/
.git/
data/
__pycache__/
*.pyc
tests/
freeze.txt
models/
!models/churn_pipeline.joblib

When you run a build, Docker first bundles a copy of the folder — the build context — and every COPY line can only pick from that bundle. Without this file, the bundle carries your 300 MB venv, the private data/customers.csv, and the whole git history. With it, our context drops from 312 MB to 2.4 MB. Read the last two lines together: models/ throws out the whole folder, then the ! line re-admits exactly one file. That pair is the "shipped deliberately" pattern — the model enters the image because a visible line says so, not because a wildcard swept it in. Delete the ! line and the model COPY in the Dockerfile fails loudly with "not found", which is the correct kind of failure.

Step 3 — the first build. One command, watched closely:

(.venv) $ docker build -t churn-service .
[+] Building 87.4s (13/13) FINISHED
 => [internal] load build definition from Dockerfile                0.0s
 => [internal] load .dockerignore                                   0.0s
 => [internal] load build context — 2.4MB                           0.1s
 => [1/8] FROM docker.io/library/python:3.12-slim                   9.8s
 => [2/8] WORKDIR /app                                              0.1s
 => [3/8] COPY requirements.txt .                                   0.0s
 => [4/8] RUN pip install --no-cache-dir -r requirements.txt       74.6s
 => [5/8] COPY config.py .                                          0.0s
 => [6/8] COPY src/ src/                                            0.0s
 => [7/8] COPY app/ app/                                            0.0s
 => [8/8] COPY models/churn_pipeline.joblib models/churn_pipeline…  0.1s
 => exporting to image                                              2.6s
 => => naming to docker.io/library/churn-service:latest             0.0s

-t churn-service names the result, and the final . says "the context is this folder". Each numbered step is one Dockerfile instruction becoming one layer — eight instructions, eight layers, stacked in order. The cost lives in two places: pulling the base (9.8 s, first time only) and the pip install (74.6 s). Everything else is fractions of a second. Remember that 74.6 s number — the whole next step is about never paying it twice.

Step 4 — the cache, measured. Change one log message in app/main.py and rebuild. Then break the order on purpose and pay the difference:

# one-line edit in app/main.py, requirements-first order:
# (Windows/PowerShell has no time command — use:
#    Measure-Command { docker build -t churn-service . } )
(.venv) $ time docker build -t churn-service .
 => CACHED [2/8] WORKDIR /app                                       0.0s
 => CACHED [3/8] COPY requirements.txt .                            0.0s
 => CACHED [4/8] RUN pip install --no-cache-dir -r requirements…    0.0s
 => CACHED [5/8] COPY config.py .                                   0.0s
 => CACHED [6/8] COPY src/ src/                                     0.0s
 => [7/8] COPY app/ app/                                            0.1s
 => [8/8] COPY models/churn_pipeline.joblib models/churn_pipeline…  0.1s
real    0m3.1s

# the wrong order — COPY . . placed before the install:
#   COPY . .
#   RUN pip install --no-cache-dir -r requirements.txt
# the same one-line edit now rebuilds the world:
 => [3/4] COPY . .                                                  0.2s
 => [4/4] RUN pip install --no-cache-dir -r requirements.txt       74.9s
real    1m24.8s

The rule behind both numbers: a layer's cache key is its instruction plus the exact bytes of every file it copies. You touched app/main.py, so step 7 changed — steps 2 through 6 still match and print CACHED, and the 74.6-second pip layer costs 0.0 s. A changed layer also invalidates every layer after it, which is why step 8 re-ran too. In the wrong-order version, COPY . . changes whenever ANY file changes, so the pip layer sitting after it dies on every edit: 3.1 s against 84.8 s. Twenty rebuilds a day is the difference between 1 minute and 28 minutes — the ordering trick is not style, it is half an hour daily.

Step 5 — run, call, read logs, stop. The container life cycle end to end:

$ docker run --name churn -p 8000:8000 churn-service
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.

# second terminal — the same caller you were in 4.2:
$ curl http://127.0.0.1:8000/health
{"status":"ok","model_loaded":true}

$ curl -X POST http://127.0.0.1:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"city": "Jalandhar", "monthly_income": 24000, "orders_last_90d": 1,
       "avg_order_value": 650, "last_order_date": "2026-03-02"}'
{"prediction":1,"churn_prob":0.7}
# Windows (PowerShell): backslash continuations are bash-only, and bare "curl"
# is an alias for Invoke-WebRequest — call curl.exe with the JSON on one line:
#   curl.exe -X POST http://127.0.0.1:8000/predict -H "Content-Type: application/json" -d '{"city": "Jalandhar", "monthly_income": 24000, "orders_last_90d": 1, "avg_order_value": 650, "last_order_date": "2026-03-02"}'

$ docker logs churn | grep "model loaded"
INFO: model loaded from models/churn_pipeline.joblib

$ docker stop churn && docker rm churn

-p 8000:8000 is the port mapping: laptop port on the left, container port on the right. Change it to -p 9000:8000 and the same service answers on localhost:9000 while the container still listens on 8000 inside — proof the box has its own network. The Jalandhar customer returns {"prediction":1,"churn_prob":0.7} — the exact verdict from 4.1's predict.py and 4.2's bare service. Same model, third body. docker logs reads the container's output from outside, and the single "model loaded" line proves the 4.2 startup discipline survived the move into the box. docker stop ends it; docker ps between the two commands would show it alive with its port column filled.

Step 6 — size sense, and config through the door. Two habits that mark a production hand:

$ docker images
REPOSITORY           TAG         SIZE
churn-service        latest      458MB
churn-service-full   latest      1.36GB     # same Dockerfile, FROM python:3.12
python               3.12-slim   125MB
python               3.12        1.02GB

# config from outside — same image, no rebuild:
$ docker run -p 8000:8000 -e CHURN_THRESHOLD=0.3 churn-service
# the borderline Patiala customer (churn_prob 0.41):
default run:               {"prediction":0,"churn_prob":0.41}
with CHURN_THRESHOLD=0.3:  {"prediction":1,"churn_prob":0.41}

Swapping one word in FROM costs 900 MB: the full base ships compilers and tools our service never calls. Slim images push faster, pull faster and patch less, so print docker images after every build and treat 500 MB as our budget line. The second half needs a two-line repo edit first: in config.py, add import os and THRESHOLD = float(os.environ.get("CHURN_THRESHOLD", "0.5")), and in app/main.py compare against config.THRESHOLD instead of the hardcoded 0.5. Rebuild once — 3 seconds, the cache working for you. Now -e sets an environment variable at run time: the same image flips a borderline customer's verdict because the risk team asked for a lower cutoff, and no rebuild happened. This is 12-factor config in one move — code in the image, settings in the environment — the same door your API keys used in 3.2, which is exactly how secrets stay out of images too.