Container Lifecycle Language

Docker container states: created → running → (paused) → exited → removed.

The Docker container lifecycle states are:
• created — the container has been created (docker create) but not started
• running — the main process (ENTRYPOINT/CMD) is executing; the container is alive
• paused — processes are suspended via SIGSTOP (docker pause); memory is preserved but CPU is not consumed
• exited (stopped) — the main process has terminated; container metadata and filesystem still exist until docker rm
• dead — Docker could not properly stop or remove the container; a rare error state requiring manual cleanup

docker ps shows only running containers. docker ps -a shows containers in all states including exited. A container must be explicitly removed with docker rm to free all resources.

Key vocabulary:
• container state — the current lifecycle phase (created / running / paused / exited / dead)
• exited — a stopped container whose main process has terminated; metadata persists until removed
• docker ps -a — lists all containers including stopped ones; without -a, shows only running containers
• docker rm — removes a stopped container and frees its filesystem and metadata

unless-stopped combines crash recovery with respect for deliberate maintenance stops.

Docker restart policies:
• no (default) — never restart automatically
• always — always restart, even after docker stop and even after Docker daemon restart
• on-failure[:max-retries] — restart only when the exit code is non-zero (a crash); clean exits and deliberate stops are not retried
• unless-stopped — restart on crash or daemon restart, but NOT if the container was deliberately stopped with docker stop

For a production database, unless-stopped is the right choice: it survives crashes and host reboots, but allows operators to run maintenance windows by simply stopping the container — it won't bounce back automatically until manually started again.

Key vocabulary:
• restart policy — a Docker container setting controlling automatic restart behaviour
• unless-stopped — restart always except after a deliberate docker stop
• on-failure — restart only on non-zero exit codes (crashes)
• always — restart regardless of how the container stopped
• maintenance window — a planned period where a service is deliberately taken offline for updates or repair

Exit code 137 = 128 + SIGKILL (9) — the process was force-killed, most often by the OOM killer.

Linux exit codes for signal-killed processes follow the convention: 128 + signal_number.
• SIGKILL = signal 9, so 128 + 9 = 137
• SIGTERM = signal 15, so 128 + 15 = 143

The OOM (Out-Of-Memory) killer is the Linux kernel component that sends SIGKILL to processes when overall or cgroup memory is exhausted. In Docker, if a container's process exceeds its --memory limit, the kernel OOM-kills it and Docker reports exit code 137.

Resolution: increase the memory limit, fix a memory leak in the application, or add memory profiling to understand the growth.

Key vocabulary:
• exit code 137 — 128 + SIGKILL (9); process was force-killed, typically by the OOM killer
• OOM killer — the Linux kernel mechanism that kills memory-hungry processes to prevent system collapse
• SIGKILL — signal 9; unconditional kill that cannot be caught or ignored by the process
• memory limit — the --memory container flag setting the cgroup memory ceiling
• cgroup — Linux control group; enforces resource limits (memory, CPU) for container processes

Orchestrators automatically replace unhealthy containers — plain Docker only flags them.

Docker health check states:
• starting — within the initial grace period; health check results don't count yet
• healthy — the health check command is passing
• unhealthy — the health check has failed --retries consecutive times

In plain Docker (no orchestration): the container stays running but is marked unhealthy in docker ps. Docker itself takes no corrective action — you must intervene.

In Docker Swarm: the Swarm manager detects unhealthy tasks and schedules replacements to maintain the desired replica count. In Kubernetes, a failing liveness probe triggers a pod restart. This automated healing is the primary reason orchestration is used for production workloads.

Key vocabulary:
• health check — a periodic command Docker executes inside a running container to assess application health
• starting — the health check grace period; failures during this phase don't count toward unhealthy
• healthy / unhealthy — the passing and failing health check states
• liveness probe — Kubernetes equivalent of a Docker health check; triggers pod restart on failure
• self-healing — an orchestrator's ability to automatically replace failed containers to maintain desired state

Standard exit code conventions: 0 = success, 1 = error, 137 = SIGKILL, 143 = SIGTERM.

Linux exit code rules:
• 0 — success; the process completed normally
• 1 — general application error; the most common non-zero exit for app bugs or config errors
• 137 — 128 + 9 (SIGKILL); force-killed by the OOM killer or docker kill
• 143 — 128 + 15 (SIGTERM); the process received SIGTERM (from docker stop) and exited

The docker stop workflow: Docker sends SIGTERM to PID 1 → waits for the grace period (default 10 s) → if the process hasn't exited, sends SIGKILL. A well-behaved container catches SIGTERM, completes in-flight work, and exits with code 143. An unresponsive container gets SIGKILL'd and exits with code 137.

Key vocabulary:
• exit code — an integer returned by a process when it terminates; 0 = success, non-zero = failure or signal
• SIGTERM — signal 15; polite shutdown request from docker stop; catchable by the application
• SIGKILL — signal 9; forceful, uncatchable kill; sent after grace period expires
• graceful shutdown — catching SIGTERM, draining in-flight requests, then exiting cleanly
• PID 1 — the first process in the container; must handle signals correctly for clean shutdowns