Containers: from the problem to operating them

1 · The problem containers actually solve essential

Here's a Friday afternoon you may recognize. Your feature works perfectly. Tests pass. You push, the deploy goes green, and then the pager buzzes: it's crashing in production. You didn't change the code — you changed machines. Three hours later you find it: the server has Python 3.9, your laptop has 3.12, and one library you rely on behaves differently between them. You lost an afternoon to a difference you couldn't even see. Multiply that across a team and it's the single most expensive class of bug in software: "but it works on my machine!"

Why it keeps happening — the invisible-state problem. Your app doesn't run on "Python." It runs on your particular Python, sitting on your particular operating system, next to your particular set of system libraries, with your particular environment variables that you set six months ago and forgot. All of that is real, load-bearing state — and none of it lives in your Git repo. Your code is version-controlled and reviewed; its environment is a pile of assumptions that happen to be true on your laptop and nowhere else guaranteed. The bug isn't in your code. The bug is that the environment is implicit.

An analogy that makes it click. Think of shipping a houseplant to a friend. You could mail the plant alone and write "keep it at 21°C, water twice a week, this specific soil" — and hope their house matches. Or you could ship the plant in its own pot, with its own soil, sealed in its own climate-controlled terrarium. The second one arrives alive no matter what their house is like, because it brought its environment with it. A container is the terrarium: it packages your app together with its exact runtime, libraries, and settings so the whole thing travels as one sealed artifact that behaves identically wherever it lands.

The common mistake is thinking "I'll just document the setup" — a README with install steps, or a wiki page listing versions. Documentation drifts the moment someone upgrades a package or a new OS image ships, and it relies on every human following it perfectly every time. A container flips this from a description you hope people honor into an artifact that is the environment. You don't tell the server what to install; you hand it the finished, frozen thing.

You build an app on your laptop; it fails on a server. Why? A different Python version, a missing system library, a different OS, an env var you set months ago and forgot. The environment is invisible state. A container makes that state explicit and shippable — the app plus its exact runtime travel together as one artifact.

env_drift.py# Why "works on my machine" happens: two environments differ in invisible ways.
def env_diff(dev, prod):
    keys = set(dev) | set(prod)
    return {k: (dev.get(k, "MISSING"), prod.get(k, "MISSING"))
            for k in keys if dev.get(k) != prod.get(k)}

dev  = {"python": "3.12", "libssl": "3.0", "TZ": "UTC",  "PILLOW": "10.2"}
prod = {"python": "3.9",  "libssl": "1.1", "TZ": "UTC"}                # older, missing Pillow
for k, (d, pr_) in env_diff(dev, prod).items():
    print(f"{k:8} dev={d:8} prod={pr_}")
print("^ every one of these is a potential 'works on my machine' bug")

python   dev=3.12     prod=3.9
libssl   dev=3.0      prod=1.1
PILLOW   dev=10.2     prod=MISSING
^ every one of these is a potential 'works on my machine' bug

2 · Container vs virtual machine essential

If you've used cloud servers before, you already know a VM — and you probably assume a container is just a smaller one. That assumption is the single most common misconception about containers, and it will lead you to wrong conclusions about speed, cost, and security. So let's kill it up front: a container is not a lightweight VM. It's a fundamentally different thing that happens to solve some of the same problems. Understanding why they differ is what lets you reason about when each is the right tool.

The apartment-building analogy. A virtual machine is like building a separate house for every tenant — each with its own foundation, plumbing, electrical, and heating. Total isolation: what happens in one house can't touch another. But every house duplicates the entire infrastructure, so it's slow to build (boots in seconds-to-minutes) and heavy (gigabytes). A container is like an apartment in one shared building: every unit has its own locked door, its own rooms, its own furniture — real isolation for daily life — but they all share the building's foundation, water main, and power. That shared infrastructure is the host kernel. Because a container doesn't rebuild the plumbing, it's tiny (megabytes) and starts almost instantly (milliseconds).

What that shared kernel actually means. A VM virtualizes hardware and then boots a complete guest operating system on top — its own kernel, its own drivers, the works. A container skips all of that: it shares the running kernel of the host and isolates only your process and its files, using kernel features (namespaces and cgroups, which you'll meet later in the track) to give that process its own private view of the filesystem, network, and process list. From inside, it feels like it has the machine to itself. From the host's point of view, it's just a normal process wearing a disguise. That's why you can pack hundreds of containers onto a host that could hold only a handful of VMs — the density difference in the table below is the whole economic argument for containers.

The honest limit — and the common mistake. The mistake is assuming "smaller and faster" means "always better." Sharing a kernel is exactly what makes containers cheap, but it also means the isolation boundary is thinner than a VM's. For your own apps that's a fine trade. For hostile multi-tenant workloads (running untrusted strangers' code side by side) or when you genuinely need a different OS kernel, the stronger, hardware-level wall of a VM still wins — which is why the cloud often runs containers inside VMs, getting both. Keep that trade in mind as you read the comparison below: every row is really a consequence of "shares the kernel" versus "brings its own."

Both isolate, but differently. A VM virtualizes hardware and runs a whole guest OS (gigabytes, boots in seconds-to-minutes). A container shares the host kernel and isolates only your process + its files (megabytes, starts in milliseconds). That efficiency is why containers, not VMs, run modern apps.

3 · Your first Dockerfile — line by line essential

The first time most people open a Dockerfile, it looks like a spell. A handful of SHOUTING keywords, no obvious structure, and somehow this produces a running program on any machine on earth. It feels like there must be a lot going on. There isn't. A Dockerfile is one of the most honest files you'll ever write — it's literally just the setup steps you'd type by hand to prepare a fresh computer, written down in order so a machine can replay them. Once you see that, the mystery evaporates.

The recipe analogy, taken seriously. Think of a Dockerfile as a recipe card, and the image it builds as the finished, frozen meal. A recipe starts from a base ("begin with a store-bought pie crust"), sets up your workspace ("clear a space on the counter"), brings in your ingredients ("add the filling"), and ends with the instruction for serving ("bake and serve"). The four instructions below map onto exactly that: start from a base image, set a working directory, copy your code in, and declare what runs when someone "serves" it. Docker reads the card top to bottom, one line at a time — there's no jumping around, no hidden control flow. The order is the logic.

Why "start FROM a base" is the key idea. The instinct of a beginner is to think a container has to build an operating system from nothing — that's the source of the "this must be complicated" feeling. It doesn't. You stand on the shoulders of a base image someone already assembled: python:3.12-slim is a tiny, tested Linux that already has Python installed. You're not manufacturing an OS; you're taking a known-good starting point and layering only your changes on top. That single idea — build on a base, add just your diff — is what makes containers fast to build and small to ship, and it's why the very first line of essentially every Dockerfile is FROM.

The one distinction that trips everyone. A Dockerfile has two kinds of lines: those that run while building the image (they shape the frozen blueprint) and the one that runs when a container starts from that image (CMD). Confusing "build time" with "run time" is the mistake behind half of all early Docker frustration — you'll meet it head-on in section 4. For now, just hold the frame: FROM, WORKDIR, and COPY assemble the meal; CMD is the note that says how to serve it. Four instructions get you running.

A Dockerfile is a recipe read top-to-bottom. Four instructions get you running:

Dockerfile# app.py
# print("Hello from inside a container!")

FROM python:3.12-slim      # 1) base image: a minimal Linux + Python 3.12
WORKDIR /app                # 2) set (and create) the working dir inside the container
COPY app.py .               # 3) copy your code from host into the image
CMD ["python", "app.py"]    # 4) the command run when a container starts

build.shdocker build -t myapp .          # build image tagged "myapp" from ./Dockerfile
docker run myapp                 # start a container from it
# -> Hello from inside a container!
docker images                    # list images (see myapp + its size)
docker ps -a                     # list containers, running + exited

Hello from inside a container!

4 · CMD vs RUN vs ENTRYPOINT (the confusing three) intermediate

These three keywords cause more confused Stack Overflow questions than almost anything else in Docker. They all look like "run a command," so beginners scatter them almost at random — put RUN python app.py and wonder why the container builds fine but does nothing when it starts, or write two CMD lines and puzzle over why only the last one takes effect. The confusion is real, but it dissolves the moment you separate one question: does this happen while I'm building the image, or while a container is running?

The theatre analogy. Picture staging a play. RUN is everything that happens during rehearsal and set construction — build the scenery, hang the lights, paint the backdrop. It happens once, before any audience arrives, and the results are baked into the finished set. When you RUN pip install, you're building the set: those libraries become a permanent part of the image. CMD and ENTRYPOINT are the opening night performance — what actually happens each time the curtain goes up (each time a container starts). You rehearse once; you perform every night.

So why two performance instructions? Because there's a subtle but useful split between "what program runs" and "what arguments it gets." ENTRYPOINT is the fixed act — the executable that always runs, the thing this image fundamentally is ("this is a backup tool"). CMD is the default version of the performance, easily swapped: it either provides the whole command (when there's no ENTRYPOINT) or supplies the default arguments to the ENTRYPOINT. The practical payoff: docker run myapp python -m pytest overrides CMD to run your tests instead of the app, without touching the image — the set is unchanged, you just performed a different scene. That override-ability is exactly why you use CMD for "the default thing the app does" and reserve ENTRYPOINT for "the one program this image exists to run."

The mistake, named. The classic error is reaching for RUN when you mean CMD — e.g. ending a Dockerfile with RUN python app.py. It "works" during the build (the app runs once, at build time, and its output vanishes into a build log), so the build succeeds and you're baffled that docker run does nothing useful. The rule that prevents it: if it sets up the image, it's RUN; if it's what the app does when it starts, it's CMD. Installing something is setup (build time). Serving requests is what the app does (run time). Hold that line and these three stop fighting you.

Beginners mix these up. RUN executes at build time (installs, baked into the image). CMD is the default command at run time (overridable). ENTRYPOINT is the fixed executable; CMD becomes its default arguments.

Dockerfile.run-vs-cmdFROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # BUILD time -> baked in
COPY . .
CMD ["python", "app.py"]                              # RUN time -> the default process
# `docker run myapp python -m pytest` overrides CMD to run tests instead

5 · Containerize a real web app intermediate

The four-line Dockerfile in section 3 is a great teaching toy, and almost nothing you'll ship looks like it. Your real apps don't just print a line and exit — they depend on a stack of third-party libraries, and they stay running, listening on a network port for requests that arrive at unpredictable times. That's two new problems the toy never had to solve: how do the dependencies get in, and how does the outside world reach a server sealed inside a container. This section closes both gaps, and it's where a container stops being a curiosity and becomes something you'd actually deploy.

Dependencies first — and why the extra RUN line. A web app needs libraries (a framework like FastAPI, a server like uvicorn). Those aren't in the base image, so you install them into the image at build time with RUN pip install — the "build the set" step from section 4. Do this once and the libraries are baked in; every container that starts from the image already has them, with no install step at launch. This is also where a small ordering habit pays off (copy requirements.txt and install before copying your source) — a caching trick CD2 explains in full, but worth noticing now.

The part that surprises everyone: a container is sealed by default. Here's the analogy that saves people hours. A running container is like a soundproof recording booth. Inside, your web server is happily shouting "I'm listening on port 8000!" — but the booth is sealed, so from the hallway (your laptop) you hear nothing. A port mapping (-p 8000:8000) is drilling a labelled hole between one port on the outside wall and one port on the inside. Only then can a request from your browser travel through the wall to the server. Beginners expect the container to be reachable just because the app is running; it isn't, and it shouldn't be — that default isolation is a security feature, and you open exactly the doors you mean to.

The mistake this section is quietly setting you up to avoid. There's a second, sneakier wall: which network interface the server binds to inside the booth. Bind it to 127.0.0.1 (loopback) and the server is only reachable from inside the container itself — you can drill all the port holes you like and still hear silence, because the server is whispering to itself in the corner. Bind to 0.0.0.0 (all interfaces) and it speaks to the whole booth, so the mapped hole actually carries its voice out. This is the number-one first-container bug, and the warning box right after the labs hammers it home. For now, watch for --host 0.0.0.0 in the CMD below and know it's load-bearing, not decoration.

Real apps have dependencies and listen on a port. Here's the app (runnable Python logic) and the Dockerfile that ships it.

app_logic.py# The routing a web framework would do — pure Python so it runs anywhere.
def handle(path):
    routes = {
        "/":        lambda: (200, {"service": "orders", "status": "ok"}),
        "/healthz": lambda: (200, {"status": "healthy"}),
    }
    h = routes.get(path)
    return h() if h else (404, {"error": "not found"})

for path in ["/", "/healthz", "/nope"]:
    print(path, "->", handle(path))

/ -> (200, {'service': 'orders', 'status': 'ok'})
/healthz -> (200, {'status': 'healthy'})
/nope -> (404, {'error': 'not found'})

Dockerfile.webFROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # e.g. fastapi, uvicorn
COPY . .
EXPOSE 8000                                          # documents the port
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

run_web.shdocker build -t webapp .
docker run -p 8000:8000 webapp        # host:8000 -> container:8000
# now http://localhost:8000 reaches the app inside the container
docker run -p 8000:8000 -e ENV=prod webapp   # pass config via env vars

6 · Debugging a container from the inside advanced

Here's the failure mode that eats afternoons, and I've watched good engineers fall into it. The container starts, the app is unreachable, so they open the Dockerfile, change a line on a hunch, rebuild (wait…), rerun, still broken, change another line, rebuild (wait…)… An hour later they've made twelve edits and understand nothing. This is debugging by guessing, and it's slow precisely because each guess costs a full build-and-run cycle. The fix is a complete change of reflex: stop editing, and go look inside the container that's already running.

The analogy: a car that won't start. You wouldn't reorder new parts from the factory on a guess — you'd pop the hood on the car in front of you. Is there fuel? Is the battery connected? A container gives you the same "pop the hood" ability, and it's more powerful than debugging a normal process because the container is a sealed, reproducible box: whatever's wrong inside it is wrong the same way every time, and you can climb in and look with the app frozen in its broken state. The two tools for looking are logs (what did it say on its way down?) and exec (open a shell inside the live container and poke around by hand).

Why docker exec is the one command to internalize. docker exec -it web bash drops you into a shell inside the running container — same filesystem, same environment variables, same working directory the app sees. Now you stop reasoning about what should be true and simply check: is app.py actually at /app? Does env show the variable you expected? Does python -c "import fastapi" succeed? You're no longer guessing about the environment; you're standing in it. That's the difference between "I think the file didn't copy" and "the file isn't here — found it."

The common mistake, and why "look inside" beats it. The trap is trusting logs alone. Logs are honest but partial: they show you what the app chose to print, which means a whole category of bugs is invisible to them. The classic is binding to 127.0.0.1 from section 5 — the server logs a cheerful "listening on 8000" and looks perfectly healthy, because from its own point of view it is. Nothing in the logs reveals that it's only reachable from inside its own booth. Shell in, run the request by hand, and the truth surfaces in seconds. Reach for these tools before touching the Dockerfile — most "works locally, not in the container" bugs are a missing file, a wrong working directory, or an unset env var, and all three are obvious the moment you're inside.

Something's wrong in the container? Don't guess — shell in and look. This is your primary debugging tool: check files, env, and run the command by hand.

debug.shdocker run -d --name web -p 8000:8000 webapp   # -d = detached (background)
docker logs web                  # what did it print / crash with?
docker logs -f web               # follow live
docker exec -it web bash         # open a shell INSIDE the running container
#   inside:  ls -la /app ; env | grep ENV ; python -c "import fastapi"
docker exec web ls /app          # run one command without a shell
docker inspect web               # full JSON: mounts, network, env, state

7 · Model the container lifecycle in Python advanced

You've been driving containers by hand — build, run, exec, stop. Now flip the seat: what if you were writing the tool that manages them? Every dashboard, every orchestrator, every "restart the crashed service" script has to answer one question constantly: given where this container is now, what is it allowed to do next? A container that's already removed can't be paused. A container that was never started can't be stopped. Getting these rules wrong is how ops tools issue nonsense commands and corrupt their own view of the world. This section builds the small, sturdy idea that keeps that from happening.

A container has a life, and the life has stages. When you run docker ps and see a status, you're seeing one snapshot of a journey: a container is created, then running, maybe paused and resumed, eventually stopped, and finally removed. The crucial part isn't the list of stages — it's that only certain moves between them make sense. This "set of states plus the legal moves between them" is one of the most reusable patterns in all of engineering: a finite state machine. You'll meet it again in parsers, in network protocols, in agent loops; containers are just a friendly place to build your first one.

The board-game analogy. Think of the states as squares on a board and the transitions as the only moves the rules permit. In chess you can't teleport your rook across a friendly pawn; in this game you can't jump from created straight to removed — you must pass through running and stopped first. Encoding the legal moves in one place (a TRANSITIONS map from each state to the set of states it may go to) means the rules live in data, and the code just enforces them. Add a new state later and you edit the map, not a tangle of if statements scattered across your program.

Why a guard beats trusting the caller. The tempting mistake is to skip the check — assume whoever calls your code will only ask for sensible transitions. They won't: a race condition, a stale dashboard, a retried request, and suddenly something tries to remove a running container. A tool without a guard silently corrupts its state and lies to you afterward. The lab below does the disciplined thing instead: every transition is validated against the allowed set for the current state, and an illegal jump raises loudly rather than quietly doing the wrong thing. Making the failure impossible-by-construction — rather than merely unlikely — is exactly the mindset that separates a demo script from tooling you'd trust in production.

Tooling that manages containers (dashboards, orchestrators) models their state machine. Building it makes docker ps states concrete — and it's real code you'd write for an internal ops tool.

lifecycle.pyclass Container:
    TRANSITIONS = {
        "created": {"running"},
        "running": {"paused", "stopped"},
        "paused":  {"running", "stopped"},
        "stopped": {"running", "removed"},
        "removed": set(),
    }
    def __init__(self, name): self.name, self.state, self.history = name, "created", ["created"]
    def to(self, new):
        if new not in self.TRANSITIONS[self.state]:
            raise ValueError(f"illegal: {self.state} -> {new}")
        self.state = new; self.history.append(new); return self

c = Container("web")
c.to("running").to("paused").to("running").to("stopped").to("running")
print(c.name, "history:", " -> ".join(c.history))
try:
    Container("x").to("removed")          # created->removed is not allowed
except ValueError as e:
    print("rejected:", e)

web history: created -> running -> paused -> running -> stopped -> running
rejected: illegal: created -> removed

8 · Professional — resource limits & cleanup professional

Here's an outage that has happened at basically every company that runs containers. Ten services share a host, humming along. One of them hits a bad input and starts leaking memory — slowly, then all at once. It doesn't just crash itself: it eats every spare byte on the machine, and now the other nine healthy services get starved and killed too. One bug, one container, and the whole host goes down. The failure wasn't the leak — leaks happen. The failure was that nothing stopped one greedy container from consuming the entire machine.

The shared-house analogy. Remember the apartment building from section 2 — containers share the host's resources. That efficiency has a dark side: shared resources can be hogged. It's like flatmates sharing one water heater. If nobody agrees on limits, the person who takes a 45-minute shower leaves everyone else in the cold. Resource limits (--memory, --cpus) are the house rule that gives each container a capped allowance, so no single tenant can drain the tank. This isn't about making any one container faster — it's about protecting the host and its neighbors from any one container's worst day.

The second, quieter outage: disk. Every image you build and every container you stop leaves something on disk. It accumulates invisibly — nobody notices the gigabytes piling up — until one day a deploy fails or the database can't write because the disk is 100% full. This is a genuine, boring, extremely common cause of production incidents, and it's entirely preventable with routine housekeeping: know how much disk your images and containers are using, and periodically reclaim the space held by dead ones. The commands below make both the capping and the cleanup concrete.

The common mistake: limits set by vibes. When people finally set a memory limit, they guess — "512MB sounds fine" — and then are baffled when a perfectly healthy container keeps getting killed. Set the ceiling below what the app actually needs at peak and the kernel will OOM-kill it (Out Of Memory) on every busy moment, turning your safety net into a self-inflicted outage. The right move, which the runnable model right after the shell lab drives home, is to measure real memory use first, find the true peak, and then set the limit comfortably above it with headroom. A limit is a guardrail, not a diet — it should catch runaways, not strangle normal work.

In production a runaway container must not starve its host. Set memory and CPU limits, and clean up dead containers/images so disks don't fill (a real outage cause).

limits.shdocker run -d --name web \
  --memory=512m --cpus=1.0 \        # cap resources -> one bad container can't sink the host
  --restart=unless-stopped \        # auto-restart on crash/reboot
  -p 8000:8000 webapp

docker stats --no-stream            # live CPU/mem per container
docker system df                    # how much disk images/containers use
docker system prune -af             # reclaim space (dangling images, stopped containers)

oom.pydef will_oom(peak_mb, limit_mb):
    return peak_mb > limit_mb

for peak, limit in [(300, 512), (700, 512)]:
    verdict = "OOM-KILLED" if will_oom(peak, limit) else "ok"
    print(f"peak {peak}MB vs limit {limit}MB -> {verdict}")
print("lesson: profile real memory use, then set the limit ABOVE peak with headroom")

peak 300MB vs limit 512MB -> ok
peak 700MB vs limit 512MB -> OOM-KILLED
lesson: profile real memory use, then set the limit ABOVE peak with headroom

9 · Tech-lead — a base-image standard + policy check tech-lead

Scale changes the problem entirely. One engineer writing one good Dockerfile is easy. Fifty engineers writing fifty Dockerfiles is a different beast: one pins python:latest (which silently changes under everyone next Tuesday), one forgets a USER line so the container runs as root, one copies a .env file and bakes a live secret into a shareable image. Individually, each is an honest slip. Collectively, they're how a fleet becomes a bloated, insecure, unreproducible mess — and no amount of "please remember the rules" in a wiki fixes it, because humans under deadline forget. This section is about the tech-lead move: making the right thing automatic instead of remembered.

Why one approved base image is such leverage. Picture a restaurant kitchen. You could let every cook buy their own ingredients from whichever shop they like — and get wildly inconsistent dishes and a few cases of food poisoning. Real kitchens don't: they standardize on approved suppliers so every plate starts from the same trusted base. An approved base image is that supplier. When every service builds FROM the same vetted, slim, patched image, you fix a security hole or shave off bloat once and the whole fleet inherits it. Divergence is the enemy of operability; a shared base is how a team of fifty stays as consistent as a team of one.

From "please remember" to "the machine checks." A standard nobody enforces is just a suggestion, and suggestions decay. The move that makes it real is to encode the policy as a lint — an automated check that reads a Dockerfile and flags every violation — and wire it into CI so it runs on every change. Now the rule isn't a paragraph a reviewer might skim past; it's a gate. A Dockerfile that pins to :latest, or omits USER, or copies .env, simply doesn't pass, and it never reaches production. The engineer gets the feedback in seconds, phrased as a fixable reason, not a scolding in code review three days later.

The common mistake: enforcing with a boolean. A tempting first version of a lint just returns pass/fail — and it's nearly useless, because a red "FAILED" with no reason sends the engineer back to guessing. The lab below does the thing good tooling does: it returns the list of reasons, each a human-readable sentence ("base image not pinned," "runs as root"), so the fix is obvious. That's the whole philosophy of a lead-built guardrail: don't just block bad work, teach the fix in the same breath. Encode the standard once, phrase the failures kindly, and let CI carry the standard so you don't have to.

A lead defines an approved base image and a policy every service must pass, so the fleet is consistent, small, and safe. Encode it as a lint that runs in CI.

dockerfile_lint.pydef lint_dockerfile(text):
    lines = [l.strip() for l in text.strip().splitlines() if l.strip() and not l.startswith("#")]
    issues = []
    froms = [l for l in lines if l.startswith("FROM ")]
    if not froms:
        issues.append("no FROM")
    elif any(f.split(":")[-1] in ("latest", froms[0].split()[1]) and ":" not in f for f in froms):
        pass
    if any(l.startswith("FROM") and (l.endswith(":latest") or ":" not in l.split()[1]) for l in froms):
        issues.append("base image not pinned to a version (avoid :latest)")
    if not any(l.startswith("USER ") for l in lines):
        issues.append("no USER -> runs as root (security risk)")
    if any(("COPY .env" in l or "ADD .env" in l) for l in lines):
        issues.append("copies .env -> secret baked into the image")
    if not any("--no-cache-dir" in l for l in lines if "pip install" in l) and any("pip install" in l for l in lines):
        issues.append("pip without --no-cache-dir -> larger image")
    return issues

bad = "FROM python:latest\nCOPY .env .\nRUN pip install -r requirements.txt\nCMD [\"python\",\"app.py\"]"
print("bad  ->", lint_dockerfile(bad))
good = "FROM python:3.12-slim\nRUN pip install --no-cache-dir -r requirements.txt\nRUN useradd app\nUSER app\nCMD [\"python\",\"app.py\"]"
print("good ->", lint_dockerfile(good) or "clean")

bad  -> ['base image not pinned to a version (avoid :latest)', 'no USER -> runs as root (security risk)', 'copies .env -> secret baked into the image', 'pip without --no-cache-dir -> larger image']
good -> clean

FROM python:3.12-slim      # minimal Linux + Python 3.12
WORKDIR /app               # set/create the working dir inside the image
COPY app.py .              # copy your code from host into the image
CMD ["python", "app.py"]    # default command when a container starts

docker build -t myapp .    # build image tagged "myapp"
docker run myapp           # start a container -> prints the greeting

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # e.g. fastapi, uvicorn
COPY . .
EXPOSE 8000                                          # documents the port
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t webapp .
docker run -p 8000:8000 webapp        # host:8000 -> container:8000

docker run -d --name web -p 8000:8000 webapp   # -d = detached (background)
docker logs web                  # what did it print / crash with?
docker logs -f web               # follow live

docker exec -it web bash         # open a shell INSIDE the running container
#   inside:  ls -la /app ; env | grep ENV ; python -c "import fastapi"

docker exec web ls /app          # run one command without a full shell
docker inspect web               # full JSON: mounts, network, env, state

class Container:
    TRANSITIONS = {
        "created": {"running"},
        "running": {"paused", "stopped"},
        "paused":  {"running", "stopped"},
        "stopped": {"running", "removed"},
        "removed": set(),
    }
    def __init__(self, name):
        self.name, self.state, self.history = name, "created", ["created"]
    def to(self, new):
        if new not in self.TRANSITIONS[self.state]:
            raise ValueError(f"illegal: {self.state} -> {new}")
        self.state = new
        self.history.append(new)
        return self

c = Container("web")
c.to("running").to("paused").to("running").to("stopped")
print(c.name, "->", " -> ".join(c.history))
try:
    Container("x").to("removed")          # created->removed is illegal
except ValueError as e:
    print("rejected:", e)

docker run -d --name web \
  --memory=512m --cpus=1.0 \        # cap resources
  --restart=unless-stopped \        # auto-restart on crash/reboot
  -p 8000:8000 webapp

docker stats --no-stream            # live CPU/mem per container
docker system df                    # disk used by images/containers
docker system prune -af             # reclaim space (dangling images, stopped containers)

def will_oom(peak_mb, limit_mb):
    return peak_mb > limit_mb

for peak, limit in [(300, 512), (700, 512)]:
    verdict = "OOM-KILLED" if will_oom(peak, limit) else "ok"
    print(f"peak {peak}MB vs limit {limit}MB -> {verdict}")

def lint_dockerfile(text):
    lines = [l.strip() for l in text.strip().splitlines()
             if l.strip() and not l.startswith("#")]
    issues = []
    froms = [l for l in lines if l.startswith("FROM ")]
    if not froms:
        issues.append("no FROM")
    if any(l.endswith(":latest") or ":" not in l.split()[1] for l in froms):
        issues.append("base image not pinned to a version (avoid :latest)")
    if not any(l.startswith("USER ") for l in lines):
        issues.append("no USER -> runs as root (security risk)")
    if any(("COPY .env" in l or "ADD .env" in l) for l in lines):
        issues.append("copies .env -> secret baked into the image")
    if any("pip install" in l for l in lines) and \
       not any("--no-cache-dir" in l for l in lines if "pip install" in l):
        issues.append("pip without --no-cache-dir -> larger image")
    return issues

bad = "FROM python:latest\nCOPY .env .\nRUN pip install -r requirements.txt"
good = "FROM python:3.12-slim\nRUN pip install --no-cache-dir -r requirements.txt\nRUN useradd app\nUSER app"
print("bad  ->", lint_dockerfile(bad))
print("good ->", lint_dockerfile(good) or "clean")

Knowledge check check yourself