Docker / Images and container fundamentals / Lesson 4

Process lifetime, arguments, and shutdown

Explain why containers start, remain alive, stop, or exit before changing restart policies.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Trace exec-form command arguments and main-process lifetime.
Interpret exit evidence, signals, and graceful shutdown boundaries.

The main process defines container lifetime

A container normally remains running while its configured main process remains alive. A short command can finish successfully and leave an exited container; that is expected behavior, not necessarily a crash. The parcel-api fixture stays in the foreground through serve_forever. Launching a background daemon from a shell and allowing the shell to exit breaks this lifetime relationship. Keep the intended application process explicit instead of adding an unrelated infinite sleep.

ENTRYPOINT and CMD form an argument contract

Exec-form instructions use JSON arrays. ENTRYPOINT can fix an executable and initial arguments, while CMD supplies default arguments that a caller may replace. Without ENTRYPOINT, an explicit runtime command replaces CMD. Shell-form commands introduce shell parsing and expansion, which can affect quoting and signal forwarding. Read the final argument vector instead of assuming that similar-looking strings launch the same executable with the same working directory.

dockerfile Alternative command fields for the existing fixture

ENTRYPOINT ["python", "-u"]
CMD ["app.py"]

Expected output

Default argv: ["python", "-u", "app.py"]

These two fields replace the CMD-only choice in the earlier complete Dockerfile; the rest of that recipe remains required. With no runtime arguments, the resulting command is python -u app.py. Supplying -m http.server 8080 replaces CMD arguments while retaining the Python entrypoint, so it starts a different program.

Read state before guessing the reason

Inspect whether the object is created, running, restarting, or exited, then correlate timestamps, exit code, and logs. An exit code of zero usually means the main process reported success; it does not mean an HTTP service stayed available. A nonzero exit points toward failure but not one universal cause. An exit such as 137 can involve SIGKILL; inspect OOMKilled and surrounding events rather than declaring every such exit an out-of-memory incident.

bash Correlate process state, actual arguments, and recent logs

docker container inspect parcel-api --format '{{json .State}}'
docker container inspect parcel-api --format '{{json .Path}} {{json .Args}}'
docker logs --tail 50 parcel-api

The inspection reads an existing authorized container and does not restart it. Actual exit codes and log lines depend on the incident, so none are fabricated. Path and Args help reveal an accidental command override even when the image configuration looked correct. Capture timestamps and redact sensitive application output.

Graceful shutdown is an application behavior

The normal stop path sends the configured stop signal, commonly SIGTERM on Linux, then waits for a grace period before forcing termination if the process remains alive. Exec form removes an unnecessary shell but does not implement application signal handlers or request draining. Services should stop accepting new work, complete or cancel in-flight work within a bound, flush necessary state, and exit. The allowed period must fit those operations and the outer supervisor's timeout.

A restart policy is not a repair mechanism

A restart policy decides whether an exited container should be started again under specified conditions. It cannot repair a missing executable, invalid configuration, or permanently inaccessible data directory. Unbounded fast restarts can hide useful failure evidence and overload dependencies. Classify a one-shot task separately from a long-running service, preserve the first failure, and apply a retry budget or operational alert rather than treating repeated starts as proof of resilience.

Common errors and fixes

The container exits immediately with code 0.

Why it happens: Its main command finished or backgrounded the real server and then ended.
How to fix it: Run the intended foreground process and verify its argument vector.
Prevent it next time: Specify whether each image is a service or a one-shot task.

exec: executable file not found in $PATH.

Why it happens: The configured executable is absent, misspelled, or outside the runtime PATH.
How to fix it: Inspect image contents, working directory, and exact executable path before rebuilding.
Prevent it next time: Keep startup commands aligned with the final image rather than the build stage.

Shutdown always reaches forced termination.

Why it happens: Signals may not reach the application, or draining exceeds its configured grace period.
How to fix it: Correct signal handling and set a justified bounded grace period.
Prevent it next time: Rehearse shutdown under in-flight load and inspect termination evidence.

Check your understanding

1. Does restart: always make an invalid configuration reliable?

Show worked solution

No. It repeatedly starts the same failing process and can produce a loop. Preserve the first error, correct the configuration through the approved deployment process, and replace the container if needed. Reliability comes from valid startup and bounded recovery behavior, not merely frequent attempts.

2. Why is exit 137 alone insufficient to diagnose memory exhaustion?