Module 01: Images & Containers
The Lifecycle & the Core CLI

Sam's goal is simple: get one web app running in a container and keep it running. From Foundations, hold these three sentences in your head, because everything in this module hangs off them:

The image is layers of read-only filesystem. Starting a container adds one thin writable layer on top (copy-on-write). Everything the running process writes lands there. Delete the container and that layer vanishes (the image layers are untouched and shared with every other container started from the same image). This is the trap Sam hit first: a config file edited inside a running container disappeared on the next run.

Two containers from the same image share the three RO layers; only the top layer differs.

This is the single most important diagram in the module. Every command you learn is a transition between these states.

One command does a lot. The first time Sam typed it, the flag order felt arbitrary. It isn't. Read it by position: the parts before the image name configure Docker, and everything after the image name is passed into the container.

The flags you'll reach for constantly

# Foreground: logs stream to your terminal, Ctrl-C stops it
docker run nginx

# Detached + named + port-mapped: the real-world pattern
docker run -d --name web -p 8080:80 nginx:1.27
# → open http://localhost:8080

# Interactive shell inside a fresh ubuntu (exits when you type `exit`)
docker run -it --rm ubuntu bash

These map one-to-one onto the lifecycle diagram. Commit the shape of each to memory.

docker ps -a                      # see everything, running or not
docker stop web                    # graceful shutdown
docker start web                   # bring it back, same writable layer
docker rm -f web                   # nuke it, running or not

# Clean up ALL stopped containers at once
docker container prune

This trio is your debugging toolkit. When a container is misbehaving, this is what you reach for.

# Get a shell inside the running 'web' container
docker exec -it web sh

# Follow logs live (like tail -f); --tail limits history
docker logs -f --tail 50 web

# Pull one field out of the JSON with a Go template
docker inspect -f '{{.State.Status}} {{.State.ExitCode}}' web
running 0

Containers come from images; images come from a registry (or your own builds). The image-side commands:

docker images
REPOSITORY   TAG     IMAGE ID       SIZE
nginx        1.27    a1b2c3d4e5f6   188MB

docker history nginx:1.27        # see how the layers were built
docker image prune -a           # free disk (careful: removes unused images)

The exact trace from Foundations, now grounded in the lifecycle. Be able to narrate this end to end:

1. Client → daemon. Your CLI sends a REST request over /var/run/docker.sock.
2. Image resolution. Daemon checks for nginx locally; if missing it pulls the layers from the registry.
3. Create. Daemon → containerd prepares the container: assembles the overlay filesystem + a writable layer, sets up namespaces. → state Created.
4. Start. runc applies cgroups and spawns PID 1 (the nginx master process). → state Running.
5. Live. Networking attached, ports published. Container lives as long as PID 1 lives.
6. Exit. PID 1 ends → Stopped. docker rm drops the writable layer → Removed.

This is the exact sequence that took Sam's app from "won't stay up" to shipped. Docker is muscle memory. Run every line, predict the output before you hit enter, then check.

# 1. Start a named web server, detached, on host port 8080
docker run -d --name web -p 8080:80 nginx:1.27

# 2. Confirm it's running, then hit it
docker ps
curl -s localhost:8080 | head -n 5

# 3. Look inside: shell in, check the nginx process is PID 1
docker exec -it web sh -c 'ps -ef | head'

# 4. Watch logs, then refresh the browser/curl and watch a line appear
docker logs -f web   # Ctrl-C to stop following

# 5. Lifecycle: stop → see it Exited → start → it's back
docker stop web && docker ps -a
docker start web

# 6. Prove the writable layer is disposable
docker exec web sh -c 'echo hi > /tmp/proof'
docker rm -f web
docker run -d --name web -p 8080:80 nginx:1.27
docker exec web ls /tmp        # /tmp/proof is GONE: new writable layer

# 7. Clean up
docker rm -f web

• You saw nginx as PID 1 inside the container.
• You watched a request appear in logs -f in real time.
• You proved a file written inside the container did not survive rm + re-run.
• You can recite: run = create + start, container lives = PID 1 lives.