1.2.2.4 Startup Command Definition

Startup command definition is the part of a Docker image that specifies what process should run when a container is started from it, expressed through the CMD and ENTRYPOINT instructions in a Dockerfile.

CMD: The Default Startup Behavior

CMD defines the default command a container runs if no other command is specified when it is started. It can be overridden at run time, which makes it suitable for defining a sensible default that callers can replace if needed.

FROM python:3.12-slim
COPY . /app
WORKDIR /app
CMD ["python", "app.py"]

docker run myapp
docker run myapp python -c "print('overridden')"

The second command replaces the default entirely, demonstrating that CMD is a suggestion rather than a fixed requirement.

ENTRYPOINT: A Fixed Executable

ENTRYPOINT defines the executable that always runs, with any arguments provided at docker run time appended to it rather than replacing it. This is useful when an image is meant to behave like a specific command-line tool.

FROM alpine:3.19
ENTRYPOINT ["echo"]

docker run myimage "hello"

This always invokes echo, with whatever argument is supplied appended, rather than allowing the entire startup command to be replaced.

Combining ENTRYPOINT and CMD

The two instructions are often combined, with ENTRYPOINT defining the fixed executable and CMD supplying default arguments that can still be overridden.

FROM python:3.12-slim
COPY . /app
WORKDIR /app
ENTRYPOINT ["python", "app.py"]
CMD ["--mode", "production"]

docker run myapp
docker run myapp --mode development

Exec Form vs Shell Form

Writing CMD or ENTRYPOINT as a JSON array (the exec form) runs the command directly as the container's main process, which correctly receives signals like SIGTERM for graceful shutdown. Writing it as a plain string (the shell form) wraps it in a shell, which can interfere with signal handling.

CMD ["python", "app.py"]

CMD python app.py

The exec form is generally preferred for application startup commands because it ensures the application process itself, not an intermediary shell, receives container lifecycle signals.

Why Startup Command Definition Matters

The startup command is what turns a packaged filesystem into a running application; everything else in the image exists to support whatever process is defined here as the thing that actually executes when the container starts.