Containers: from the problem to operating them

This tiny program makes the famous "but it works on my machine!" problem visible. Your laptop (dev) and the server (prod) are each just a bag of settings — Python version, system libraries, time zone, installed packages. When those bags quietly differ, your app breaks in one place but not the other. This code lists exactly what differs.

1. dev and prod are two dictionaries — each is a name→value list describing an environment (e.g. "python": "3.12").
2. env_diff collects every key seen in either environment (set(dev) | set(prod) is the union), then keeps only the keys whose values disagree. dev.get(k, "MISSING") returns "MISSING" when a key exists in one environment but not the other.
3. The for loop prints each mismatch as key dev=… prod=… so you can eyeball the drift.

What the output means: Three lines: Python is 3.12 on dev but 3.9 on prod, libssl differs, and Pillow is installed on dev but MISSING on prod. Each mismatch is a bug waiting to happen — and a container fixes it by shipping one frozen environment everywhere.

Try this: Add "NUMPY": "1.26" to dev only and re-run — it shows up as MISSING on prod. That is the invisible state containers make explicit.

A Dockerfile is the recipe for building an image (the frozen blueprint of your app + its environment). Docker reads it top to bottom, running one instruction per line. These four instructions are all you need to package a program.

1. FROM python:3.12-slim — the base image you build on top of: a tiny Linux that already has Python 3.12. Every Dockerfile starts with a FROM.
2. WORKDIR /app — sets the folder inside the image where later commands run (and creates it). Think of it as cd /app that sticks.
3. COPY app.py . — copies app.py from your machine into the image (the . means "into the current WORKDIR"). Your code now travels with the image.
4. CMD ["python", "app.py"] — the default command that runs when someone starts a container from this image. FROM/WORKDIR/COPY build the image; CMD is what happens at run time.

Try this: The two # lines at the top just show what app.py contains (it prints a greeting). Change that greeting in your real app.py and rebuild to see the new message.

You have a Dockerfile — now turn it into a running container with two commands. This is the core build → run loop you'll repeat constantly. These run in your terminal (they need Docker installed).

1. docker build -t myapp . — reads the Dockerfile in the current folder (the .) and produces an image. -t myapp tags (names) it myapp so you can refer to it later.
2. docker run myapp — starts a container (a running instance) from that image. It executes the image's CMD, so you see Hello from inside a container! printed.
3. docker images lists the images you've built (name + size); docker ps -a lists containers — the -a shows all of them, including ones that already finished and exited.

What the output means: The greeting prints, proving the container ran your code. Image vs container: the image is the saved blueprint on disk; a container is one live run of it — you can start many containers from one image.

Try this: Run docker run myapp a second time, then docker ps -a — you'll see two exited containers from the same image. One blueprint, many runs.

Beginners mix up RUN and CMD. This Dockerfile shows the difference in context: RUN happens while building the image (once, baked in); CMD happens when a container starts (every run, and easily overridden).

1. COPY requirements.txt . then RUN pip install … -r requirements.txt — RUN executes at build time, so the installed libraries become part of the image. You pay this cost once, not on every start.
2. COPY . . copies the rest of your source in after installing deps (a small speed trick you'll see explained in CD2).
3. CMD ["python", "app.py"] is the default process a container runs. It's not baked like RUN — the comment shows docker run myapp python -m pytest overriding it to run tests instead.

Try this: Remember the rule: RUN = set up the image (build time); CMD = the default thing it does (run time). If you install something, it's RUN; if it's "what the app does", it's CMD.

Before containerizing a web app, here's the app's routing logic — the part that decides what to answer for each URL path. It's written as plain Python (no web framework) so it runs anywhere and you can see the idea clearly.

1. routes is a dictionary mapping each URL path to a small function (lambda) that returns a (status_code, body) pair — e.g. 200 means OK, 404 means not found.
2. routes.get(path) looks up the path. If it's found, h() calls that function; if not, we fall back to a 404 not found response.
3. The for loop tries three paths — a real one, the health check /healthz, and a missing one — and prints what each returns.

What the output means: Three lines: / and /healthz return 200 with their data; /nope returns 404. A real framework (FastAPI) does exactly this matching for you — the Dockerfile below ships that framework version.

Try this: Add a new route like "/version": lambda: (200, {"v": "1.0"}) to the dictionary and add "/version" to the loop. This is how you'd add an endpoint to the real app.

This is a real, production-shaped Dockerfile: it installs dependencies, copies your app, and starts a web server that listens on a port. It's the minimal Dockerfile from earlier plus two web-specific pieces.

1. COPY requirements.txt . + RUN pip install --no-cache-dir -r requirements.txt installs your libraries (e.g. fastapi, uvicorn) at build time. --no-cache-dir skips pip's cache to keep the image smaller.
2. EXPOSE 8000 documents that the app listens on port 8000. It's a note for humans and tools — it does not by itself open the port to your machine (the -p flag at run time does that).
3. CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] starts the web server. --host 0.0.0.0 is critical (see the warning below) and --port 8000 matches the EXPOSE.

Try this: Compare this to the four-line Dockerfile in section 3: same shape (FROM→WORKDIR→COPY→CMD), just with a RUN pip install for dependencies and an EXPOSE for the port.

Now run the web app so your browser can reach it. The new idea is port mapping: a container's ports are sealed off by default, so you must explicitly connect a port on your machine to a port inside the container.

1. docker build -t webapp . builds and tags the image webapp, just like before.
2. docker run -p 8000:8000 webapp — the -p host:container flag maps your port 8000 to the container's port 8000. Reading it as 8000:8000 = outside:inside. Now http://localhost:8000 reaches the app.
3. docker run -p 8000:8000 -e ENV=prod webapp adds -e ENV=prod, which sets an environment variable inside the container — the standard way to pass config (which database, which mode) without changing the image.

Try this: Change the left number: -p 9000:8000. Now the app is reachable at http://localhost:9000 even though it still listens on 8000 inside. The mapping translates outside→inside.

When a container misbehaves, don't guess — look inside it. These commands are your core debugging toolkit: read its logs, and open a shell in the running container to inspect files, environment, and dependencies by hand.

1. docker run -d --name web -p 8000:8000 webapp — -d runs it detached (in the background) and --name web gives it a friendly name so you don't need its long ID.
2. docker logs web shows everything the app printed (and any crash message); docker logs -f web follows it live, like tail -f.
3. docker exec -it web bash opens an interactive shell inside the running container — the single most useful debugging command. Now you can ls the files, check env, and try imports exactly as the container sees them.
4. docker exec web ls /app runs one command without a full shell; docker inspect web dumps the container's full configuration as JSON (mounts, network, env, current state).

Try this: Most "works locally, not in the container" bugs are a missing file, a wrong working directory, or an unset env var. exec in and re-run the command by hand — you'll usually spot it in seconds.

A container moves through a fixed set of states (created → running → paused → stopped → removed), and only certain jumps between them are legal. This is a state machine. Modeling it in Python is exactly the kind of code you'd write for an ops dashboard, and it makes the states from docker ps concrete.

1. TRANSITIONS is a dictionary saying, for each state, which states you're allowed to move to next. For example "running": {"paused", "stopped"} means a running container may pause or stop — but not jump straight to removed.
2. __init__ starts every container in the "created" state and keeps a history list of where it's been.
3. to(new) is the guard: if new isn't in the allowed set for the current state, it raises a ValueError. Otherwise it updates the state and records it. Returning self lets you chain calls like c.to("running").to("paused").
4. The try/except at the bottom deliberately attempts an illegal jump (created → removed) to show the guard rejecting it instead of allowing a nonsense transition.

What the output means: First line prints the full legal history; the second prints rejected: illegal: created -> removed — proof the state machine blocks impossible transitions.

Try this: Add "exited" as a new state, or try c.to("removed") while c is running — the guard will reject it because only stopped containers can be removed.

In production, one runaway container must not crash the whole host, and dead images must not fill the disk. These commands set resource limits and do housekeeping — real habits that prevent real outages.

1. --memory=512m --cpus=1.0 cap how much RAM and CPU the container may use, so a single misbehaving container can't starve the machine. (The \ at line ends just continues one long command across lines.)
2. --restart=unless-stopped tells Docker to automatically restart the container if it crashes or the host reboots — unless you stopped it on purpose.
3. docker stats --no-stream prints a one-shot snapshot of live CPU/memory per container; docker system df shows how much disk images and containers are using.
4. docker system prune -af reclaims space by deleting unused (dangling) images and stopped containers. -a = all unused, -f = don't ask for confirmation.

Try this: Run docker system df before and after docker system prune -af to see the disk you get back. On a busy machine this can free gigabytes.

This models what happens when a container needs more memory than its limit allows: the kernel OOM-kills it (Out Of Memory). The code is trivial on purpose — the point is the lesson about how to choose a safe limit.

1. will_oom(peak_mb, limit_mb) just returns whether the app's peak memory use exceeds the limit you set. If it does, Docker kills the container to protect the host.
2. The loop tries two cases: peak 300MB under a 512MB limit (fine), and peak 700MB under the same 512MB limit (over → killed).

What the output means: peak 300MB … -> ok and peak 700MB … -> OOM-KILLED. The takeaway line says it all: measure real memory use, then set the limit above the peak with headroom — too tight and healthy containers die.

Try this: Change the pairs to (500, 512) — barely under. It says ok, but in real life a spike would kill it. That's why you leave headroom above the observed peak.

A tech lead encodes the team's Docker rules as an automated lint — a check that scans a Dockerfile and flags policy violations, so every service ends up small, secure, and consistent without each engineer remembering the rules. This is that check.

1. The first line splits the Dockerfile into non-empty, non-comment lines so the checks can scan them.
2. It flags a base image not pinned to a version (using :latest or no tag is risky — the image can change under you); a missing USER line (so the container would run as root, a security risk); copying .env (which would bake secrets into the image); and pip install without --no-cache-dir (which bloats the image).
3. It returns a list of issues — empty means the Dockerfile passed.
4. The two examples at the bottom run the linter on a deliberately bad Dockerfile and a good one to show both outcomes.

What the output means: bad prints a list of four problems; good prints clean (issues or "clean" falls back to the word when the list is empty). Dropped into CI, this rejects a bad Dockerfile before it ships.

Try this: Remove the USER app line from the good string and re-run — the linter now flags "runs as root". That is your policy catching a regression automatically.