Use Entrypoint with Docker and Docker Compose

Use Entrypoint with Docker and Docker Compose

In this tutorial I will explain how Docker’s Entrypoint instruction works and how you can use it in your Dockerfiles and with Docker Compose. This will also cover some best practices and ideas for where you can learn more.

Entrypoint sets the command and parameters that will be executed first when a container is run.

What does Entrypoint do?

Entrypoint sets the command and parameters that will be executed first when a container is run.

Any command line arguments passed to docker run <image> will be appended to the entrypoint command, and will override all elements specified using CMD. For example, docker run <image> bash will add the command argument bash to the end of the entrypoint.

Dockerfile ENTRYPOINT

Dockerfiles use all uppercase letters for the entrypoint instruction. There are several ways you can define this.

The exec syntax

The exec form is where you specify commands and arguments as a JSON array. This means you need to use double quotes rather than single quotes.

ENTRYPOINT ["executable", "param1", "param2"]

Using this syntax, Docker will not use a command shell, which means that normal shell processing does not happen. If you need shell processing features, then you can start the JSON array with the shell command.

ENTRYPOINT [ "sh", "-c", "echo $HOME" ]

Using an entrypoint script

Another option is to use a script to run entrypoint commands for the container. By convention, it often includes entrypoint in the name. In this script, you can setup the app as well as load any configuration and environment variables. Here is an example of how you can run it in a Dockerfile with the ENTRYPOINT exec syntax.

COPY ./docker-entrypoint.sh /
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["postgres"]

For example, the Postgres Official Image uses the following script as its ENTRYPOINT:

#!/bin/bash
set -e
if [ "$1" = 'postgres' ]; then
    chown -R postgres "$PGDATA"
if [ -z "$(ls -A "$PGDATA")" ]; then
        gosu postgres initdb
    fi
exec gosu postgres "$@"
fi
exec "$@"

Docker Compose entrypoint

The instruction that you use in your Docker Compose files is the same, except you use lowercase letters.

entrypoint: /code/entrypoint.sh

You can also define the entrypoint with lists in your docker-compose.yml.

entrypoint:
    - php
    - -d
    - zend_extension=/usr/local/lib/php/xdebug.so
    - -d
    - memory_limit=-1
    - vendor/bin/phpunit

Overriding Entrypoint

You can override entrypoint instructions using the --entrypoint flag.

Syntax best practices

As well as the exec syntax, Docker allows shell syntax as another valid option for both ENTRYPOINT and CMD. This executes this command as a string and performs variable substitution.

  • ENTRYPOINT command param1 param2

The Dockerfile reference explains out some of the issues.

The ENTRYPOINT shell form prevents any CMD or run command line arguments from being used, but has the disadvantage that your ENTRYPOINT will be started as a subcommand of /bin/sh -c, which does not pass signals. This means that the executable will not be the container’s PID 1 – and will not receive Unix signals – so your executable will not receive a SIGTERM from docker stop <container>

If CMD is used to provide default arguments for the ENTRYPOINT instruction, both the CMD and ENTRYPOINT instructions should be specified with the JSON array format.

Source