A container isn't just "running" or "stopped." It's a state machine with discrete states, well-defined transitions, and kernel-level mechanisms behind each one. Understanding this machine is essential to designing reliable architectures that handle crashes, restarts, and graceful shutdowns.

1. The State Machine

Every Docker container passes through a set of discrete states. Each transition is triggered by a specific command or system event:

• Created — Container exists (writable layer + config allocated) but no process running
• Running — PID 1 process is active inside the container's namespaces
• Paused — Process frozen via cgroup freezer; still in memory, consuming no CPU
• Stopped (Exited) — PID 1 has terminated; writable layer and metadata still on disk
• Dead — Partially removed container in a broken state (resource cleanup failed)

2. Create vs Run

docker run is actually two operations combined: docker create + docker start.

What docker create does

1. Pulls the image (if not cached)
2. Allocates a writable container layer (copy-on-write filesystem)
3. Stores the container configuration (env vars, mounts, network, entrypoint)
4. Assigns a container ID — returns it without starting any process

When to use create separately

• Init containers — pre-create containers that run setup tasks before the main app
• Pre-warming — create containers ahead of time so startup latency is just the process fork, not image pull + layer allocation
• Batch scheduling — create a pool of containers, then start them in a controlled sequence
• Configuration injection — inspect/modify the config between create and start

# Create without starting
docker create --name my-app -p 8080:80 nginx:alpine
# Container is now in "Created" state
docker inspect --format '{{.State.Status}}' my-app
# → "created"

# Start when ready
docker start my-app
# → "running"

3. Starting & Stopping

Starting a container

When you issue docker start, the Docker daemon:

1. Sets up namespaces (PID, NET, MNT, UTS, IPC, USER)
2. Configures cgroups for resource limits
3. Prepares the overlay filesystem mount
4. Forks the container's PID 1 process (the entrypoint)
5. If the container was previously stopped, sends SIGCONT to resume

Stopping a container

docker stop follows a two-phase shutdown:

# Stop with default 10s grace period
docker stop my-app

# Stop with custom grace period (30 seconds for DB to drain)
docker stop --time 30 my-app

# Immediate kill (no grace period)
docker kill my-app

4. Pause & Unpause

docker pause uses the cgroup freezer subsystem to suspend all processes in the container. Unlike stop, the processes remain in memory — they're just not scheduled by the CPU.

Use cases for pause

• Filesystem snapshots — freeze the container to get a consistent snapshot of the writable layer (docker commit)
• Temporary resource relief — free CPU without the cost of full restart
• Debugging — freeze a misbehaving container to inspect its state without it continuing to cause damage

# Pause a running container
docker pause my-app
docker inspect --format '{{.State.Status}}' my-app
# → "paused"

# Resume it
docker unpause my-app

5. Restart Policies

Restart policies tell the Docker daemon what to do when a container exits. They are set at container creation time with --restart:

# Restart on failure, max 5 attempts
docker run -d --restart=on-failure:5 --name worker my-worker-image

# Always restart (survives daemon restarts)
docker run -d --restart=always --name api my-api-image

# Check restart count
docker inspect --format '{{.RestartCount}}' worker

6. Removing Containers

Stopped containers still consume disk space (writable layer + metadata). You must explicitly remove them:

# Remove a stopped container
docker rm my-app

# Force-remove a running container (sends SIGKILL first)
docker rm -f my-app

# Remove all stopped containers
docker container prune

# Auto-remove when container exits (great for one-off tasks)
docker run --rm alpine echo "I clean up after myself"

Orphaned containers and disk space

Every stopped container retains its writable layer. On a busy CI server running hundreds of builds, this accumulates fast:

# See how much space stopped containers use
docker system df

# Typical output on an unmanaged host:
# Containers: 847   Size: 12.4GB (reclaimable: 11.8GB)

7. Exit Codes

When a container stops, its exit code tells you why. Learn to read them:

# Check exit code of a stopped container
docker inspect --format '{{.State.ExitCode}}' my-app

# Debugging workflow
docker ps -a --filter "exited=137"  # Find OOM-killed containers
docker logs my-app                   # Check app logs before death
docker inspect my-app | jq '.[0].State'  # Full state details

Interactive Quizzes

Hands-On Tasks

# Step 1: Create (don't start)
docker create --name lifecycle-test alpine sleep 30
docker inspect --format '{{.State.Status}}' lifecycle-test
# Expected: "created"

# Step 2: Start it
docker start lifecycle-test
docker inspect --format '{{.State.Status}}' lifecycle-test
# Expected: "running"

# Step 3: Pause and inspect
docker pause lifecycle-test
docker inspect --format '{{.State.Status}}' lifecycle-test
# Expected: "paused"

# Step 4: Unpause, then stop
docker unpause lifecycle-test
docker stop --time 5 lifecycle-test
docker inspect --format '{{.State.Status}}' lifecycle-test
# Expected: "exited"

# Step 5: Check exit code
docker inspect --format '{{.State.ExitCode}}' lifecycle-test
# Expected: 137 (SIGKILL after grace period, since sleep doesn't handle SIGTERM)

# Clean up
docker rm lifecycle-test

# Run a container that exits with error code 1 after 2 seconds
docker run -d --name restart-test \
  --restart=on-failure:3 \
  alpine sh -c "echo 'Starting...'; sleep 2; echo 'Crashing!'; exit 1"

# Watch the restart count increase (check every 5 seconds)
watch -n 5 'docker inspect --format "Restarts: {{.RestartCount}} | Status: {{.State.Status}}" restart-test'

# After 3 restarts, the container stays stopped
# You should eventually see: Restarts: 3 | Status: exited

# Inspect the full restart history
docker inspect --format '{{json .RestartCount}}' restart-test

# Compare with a successful exit (no restart triggered)
docker run -d --name success-test \
  --restart=on-failure:3 \
  alpine sh -c "echo 'Done'; exit 0"

docker inspect --format '{{.RestartCount}}' success-test
# Expected: 0

# Clean up
docker rm -f restart-test success-test

# Kubernetes pod spec with lifecycle hooks
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: api
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 5 && kill -TERM 1"]

Key Takeaways

• Containers are state machines — Created → Running → Paused/Stopped → Dead. Know what triggers each transition.
• docker run = create + start — separate them when you need pre-warming or staged orchestration.
• Always handle SIGTERM — your app gets 10 seconds by default to shut down gracefully. Use them to close connections, flush writes, and deregister from load balancers.
• Pause ≠ Stop — pause freezes the process in place (cgroup freezer); stop terminates it. Choose based on whether you need the memory back.
• Restart policies are your first line of resilience — use on-failure for workers, unless-stopped for services, never always for one-off tasks.
• Exit codes tell the story — 137 means OOM/kill, 143 means graceful SIGTERM, 127 means missing binary. Read them before reading logs.
• Clean up after yourself — use --rm for ephemeral containers, docker container prune regularly, and monitor docker system df.