4.3.3.3 Startup Command Clarity
A focused guide to Startup Command Clarity, connecting core concepts with practical Docker and container operations.
Startup command clarity is the practice of writing a Dockerfile's CMD or ENTRYPOINT instruction in a way that unambiguously communicates exactly what process actually runs when a container starts, avoiding subtle confusion around shell form versus exec form and around how the two instructions interact.
Preferring Exec Form for Clarity and Correctness
Exec form (a JSON array) directly specifies the executable and its arguments, avoiding the implicit shell wrapper that shell form introduces — that wrapper can behave unexpectedly around signal handling and process identity.
CMD node server.js
CMD ["node", "server.js"]
The second, exec form, runs node directly as process ID 1 inside the container; the first runs it as a child of an implicit shell, which can complicate how the process receives termination signals.
Making the ENTRYPOINT and CMD Relationship Explicit
When both ENTRYPOINT and CMD are used together, the relationship between them — a fixed executable plus configurable default arguments — should be obvious from reading the two instructions together, ideally accompanied by a brief comment if the interaction is not immediately self-evident.
ENTRYPOINT ["python", "manage.py"]
CMD ["runserver", "0.0.0.0:8000"]
Together, these produce python manage.py runserver 0.0.0.0:8000 by default, with the CMD portion easily overridable at run time while the ENTRYPOINT portion remains fixed.
Avoiding Ambiguous or Overly Clever Startup Logic
A startup command that relies on a complex inline shell expression, rather than a clearly named startup script, can be difficult for a reader to verify correctly without manually tracing through shell semantics.
CMD ["sh", "-c", "if [ \"$ENV\" = production ]; then exec gunicorn app:app; else exec flask run; fi"]
COPY docker-entrypoint.sh /usr/local/bin/
CMD ["docker-entrypoint.sh"]
Moving complex startup logic into a dedicated, clearly named script that can be reviewed and tested independently is generally clearer than an inline shell conditional.
Why Startup Command Clarity Matters
Because the startup command determines exactly what a container actually does once running, writing it unambiguously — in exec form, with a clear ENTRYPOINT/CMD relationship, and without unnecessary inline complexity — directly affects how confidently anyone can predict and verify a container's actual runtime behavior.