Using CMD and ENTRYPOINT in Dockerfiles

Overview

Teaching: 20 min
Exercises: 10 min

Questions

• How are default commands set in Dockerfiles?

Objectives

• Learn how and when to use CMD

• Learn how and when to use ENTRYPOINT

So far everytime we’ve run the Docker containers we’ve typed

docker run --rm -ti <IMAGE>:<TAG> <command>

like

docker run --rm -ti python:3.9 /bin/bash

Running this dumps us into a Bash session

printenv | grep SHELL

SHELL=/bin/bash

However, if no /bin/bash is given then you are placed inside the Python 3.9 REPL.

docker run --rm -ti python:3.9

Python 3.9.7 (default, Oct 13 2021, 09:00:49)
[GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

These are very different behaviors, so let’s understand what is happening.

The Python 3.9 Docker image has a default command that runs when the container is executed, which is specified in the Dockerfile with CMD.

# Dockerfile.defaults
# Make the base image configurable
ARG BASE_IMAGE=python:3.9-bullseye
FROM ${BASE_IMAGE}

USER root

RUN apt-get -qq -y update && \
    apt-get -qq -y upgrade && \
    apt-get -y autoclean && \
    apt-get -y autoremove && \
    rm -rf /var/lib/apt/lists/*

# Create user "docker"
RUN useradd -m docker && \
    cp /root/.bashrc /home/docker/ && \
    mkdir /home/docker/data && \
    chown -R --from=root docker /home/docker

ENV HOME /home/docker
WORKDIR ${HOME}/data
USER docker

CMD ["/bin/bash"]

docker build -f Dockerfile.defaults -t defaults-example:latest --compress .

Now running

docker run --rm -ti defaults-example:latest

again drops you into a Bash shell as specified by CMD. As has already been seen, CMD can be overridden by giving a command after the image

docker run --rm -ti defaults-example:latest python

The ENTRYPOINT builder command allows to define a command or commands that are always run at the “entry” to the Docker container. If an ENTRYPOINT has been defined then CMD provides optional inputs to the ENTRYPOINT.

# entrypoint.sh
#!/usr/bin/env bash

set -e

function main() {
    if [[ $# -eq 0 ]]; then
        printf "\nHello, World!\n"
    else
        printf "\nHello, %s!\n" "${1}"
    fi
}

main "$@"

/bin/bash

# Dockerfile.defaults
# Make the base image configurable
ARG BASE_IMAGE=python:3.9-bullseye
FROM ${BASE_IMAGE}

USER root

RUN apt-get -qq -y update && \
    apt-get -qq -y upgrade && \
    apt-get -y autoclean && \
    apt-get -y autoremove && \
    rm -rf /var/lib/apt/lists/*

# Create user "docker"
RUN useradd -m docker && \
    cp /root/.bashrc /home/docker/ && \
    mkdir /home/docker/data && \
    chown -R --from=root docker /home/docker

ENV HOME /home/docker
WORKDIR ${HOME}/data
USER docker

COPY entrypoint.sh $HOME/entrypoint.sh
ENTRYPOINT ["/bin/bash", "/home/docker/entrypoint.sh"]
CMD ["Docker"]

docker build -f Dockerfile.defaults -t defaults-example:latest --compress .

So now

docker run --rm -ti defaults-example:latest

Hello, Docker!
docker@2a99ffabb512:~/data$

Applied ENTRYPOINT and CMD

What will be the output of

docker run --rm -ti defaults-example:latest $USER

and why?

Solution

Hello, <your user name>!
docker@2a99ffabb512:~/data$

$USER is evaluated and then overrides the default CMD to be passed to entrypoint.sh

Key Points

• CMD provide defaults for an executing container

• CMD can provide options for ENTRYPOINT

• ENTRYPOINT allows you to configure commands that will always run for an executing container