How to Use Docker Run –entrypoint

Docker is a way for developers to package applications with all their dependencies and configurations into a single image that can run on any setup, making it easy to port applications across machines in a consistent manner that removes all complaints such as “it works on my machine”. These images or containers are designed to conform to the “One container, one responsibility” mantra, echoing the philosophy of Unix that recommends building small, single-purpose tools. The Docker run “entrypoint” argument is a way to override the default command used by Docker when starting a container.

Startup Commands in Docker

Since a docker container is self-contained, and ideally performs a single function, it makes sense to have a default “startup” command that gets it working. So for example, if we have a docker container for a web server, you want to be able to run the docker command to start it like this:

docker run nginx

The above command starts the nginx web server; ideally, the user shouldn’t have to do anything further. You don’t want to bother the user with running the startup command manually like this, for example:

docker run nginx nginx -g "daemon off;"

No one wants to do something like the above. As a user of docker, you want to run the web server container and forget about it. You don’t want to know about, or even think of the lower-level details and configuration of how it runs. This is one of the things that makes docker so powerful – you can just download and run an image of a webserver with no additional configuration, whatsoever.

Default Commands

To get the container “started”, docker applications always have default commands that run when the container is created. Otherwise, the container exits immediately with no processes running inside. To specify these default commands, docker has two directives:

1. CMD
2. ENTRYPOINT

Both of these commands can be used to specify a startup command for the container. CMD is a default command that is easy to override by providing additional arguments. For example, if our nginx docker has a CMD command, the following will replace the default “nginx” CMD command:

docker run nginx echo "Hello, World!"

Of course in this case, this isn’t useful. The container will print “Hello, World!” and exit.

The ENTRYPOINT command, on the other hand, is a bit more permanent. Adding additional arguments to a container with “run” simply appends them to the existing ENTRYPOINT command, which might not always make sense, and could cause a failure of the container.

However, the ENTRYPOINT directive can still be overridden with the –entrypoint flag, which means the overriding has to be more intentional.

Choosing Between ENTRYPOINT and CMD

If your docker container is a fixed program or service that can only run one thing, and where it doesn’t make sense for it to run anything else, then you should use the ENTRYPOINT directive. If, however, you think the user might wish to supply their own commands, and merely want the default command and arguments to be a suggestion, using CMD is the better choice.

So for containers like web servers, database servers, etc., use ENTRYPOINT. You can even combine the two like this:

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

The above command will run the “nginx” command, using the CMD directive as arguments. When the container is created, you can supply your own arguments to the “docker run” command, which will override the CMD arguments to ENTRYPOINT, but won’t change the ENTRYPOINT command itself.

Overriding the ENTRYPOINT Directive

While you can’t override the ENTRYPOINT directive by simply adding arguments to the “docker run” command, you can make a deliberate choice to do so by including the –entrypoint flag.

For example, the following command:

docker run --entrypoint "/bin/bash" demo-image -c "echo Overridden ENTRYPOINT"

This command creates a container from the “demo-image” image, and the -c command passes the “echo” command to the shell /bin/bash. Here, it doesn’t matter what the ENTRYPOINT directive was in the original image, because we’ve overridden it with –entrypoint.

Just as without –entrypoint, any commands you pass at the end of the docker command will replace the CMD directive. You can combine all three commands (–entrypoint, -c, and regular arguments) to craft the exact sequence of commands that should be run when your container starts. Of course, to do so, it helps if you can read and interpret the Dockerfile to see what already exists.

Why Override ENTRYPOINT?

We’ve seen that the ENTRYPOINT directive is the command the container was built to run. A docker container that doesn’t run its ENTRYPOINT command has no reason to exist, and it might as well end immediately. Given this, what are the possible reasons why you might want to override the ENTRYPOINT and replace it with something of your own?

Debugging

If a container isn’t working as expected, the developer might want to enter the container and see for themselves what’s going on. In such a situation, if the container is failing to start because the ENTRYPOINT command isn’t working, then the container would simply exit immediately, without giving a chance for any debugging. So a command like:

docker run --entrypoint "/bin/bash" my-image

This command would run the container and open a bash terminal inside it. From here, a developer can poke around and see what’s causing the problem. This is probably the biggest use-case of the –entrypoint parameter.

Running Set Up Commands

A docker container is meant to be a “plug-and-play” solution for services like web servers and databases. The creator is meant to include all dependencies and ensure that all configuration files are perfectly implemented so that you don’t have to. After all, without that assurance, what’s the purpose of running docker in the first place?

But sometimes the creator or a docker image might be behind the curve on changing some stuff, or perhaps you simply have a different way of doing things and need to make some config file changes before running the container. In such situations, it makes sense to have a different command execute before the container runs.

For example, you could open a shell and make the config changes manually before running the main command. Of course, these will be wiped out when you run the container again, so it’s only a temporary fix.

Running Administrative Commands

Sometimes, you might want to perform specific admin actions instead of running the intended command of the container, but don’t want to change the fundamental operations of the container itself. For example, you might want to first run a migration script or perform some maintenance via another script before the docker container runs its primary command. You can always include the command inside the script you want it to run, thereby ensuring that the maintenance comes first.

There are all kinds of reasons why you might want to override a given container’s ENTRYPOINT. The above are just three examples.

Conclusion

Most docker images have an ENTRYPOINT directive in their Dockerfile that runs the process defining the container. As such, you don’t normally need to change or override this. However, there are situations involving debugging or maintenance tasks that might necessitate a new command running in its place. For this, the docker run –entrypoint flag is the tool of choice.