Dockerfile commands

Docker has documentation on how to write a Dockerfile at https://docs.docker.com/engine/reference/builder/, and a set of best practices that they recommend at https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/. We will cover some of the commands that are common and important to know for building your own container images.

The following are some of the important Dockerfile build commands that you should be aware of:

1. FROM (https://docs.docker.com/engine/reference/builder/#from): FROM describes the image that you are using as a base to build your container, and is generally the first command in a Dockerfile. Docker best practices encourage the use of Debian as a base Linux distribution. As you saw from my example earlier, I prefer to use Alpine Linux because it is very compact in size. You can also use Ubuntu, Fedora, and CentOS, all of which are larger images and include significantly more software in their base image. If you are already familiar with a distribution of Linux and the tools that are used with it, then I recommend you take advantage of that knowledge for making your first containers. You can also frequently find containers built specifically to support the language you're using, such as Node or Python. At the time of writing (fall 2017), I downloaded a variety of these images to show the relative sizes:

REPOSITORY     TAG         IMAGE ID        CREATED          SIZE
alpine         latest      76da55c8019d    2 days ago       3.97MB
debian         latest      72ef1cf971d1    2 days ago       100MB
fedora         latest      ee17cf9e0828    2 days ago       231MB
centos         latest      196e0ce0c9fb    27 hours ago     197MB
ubuntu         latest      8b72bba4485f    2 days ago       120MB
ubuntu         16.10       7d3f705d307c    8 weeks ago      107MB
python         latest      26acbad26a2c    2 days ago       690MB
node           latest      de1099630c13    24 hours ago     673MB
java           latest      d23bdf5b1b1b    8 months ago     643MB

As you can see, the images vary considerably in size.

You can explore these (and a wide variety of other base images) at https://hub.docker.com/explore/.

2. RUN (https://docs.docker.com/engine/reference/builder/#run): RUN describes commands that you run within the container image that you're building, most frequently used for adding in dependencies or other libraries. If you look at Dockerfiles created by others, you'll often see the RUN command used to install libraries using commands such as apt-get install ... or rpm -ivh .... The commands that are used are specific to the choice of base image; apt-get, for example, is available on Debian and Ubuntu base images, but not on Alpine or Fedora. If you put in a RUN command that's not available (or just has a typo), then when you're running the docker build command you'll see an error. As an example, when building the Dockerfile:

FROM alpine
RUN apt-get install nodejs
Results in the following output:
Sending build context to Docker daemon  2.048kB
Step 1/2 : FROM alpine
 ---> 76da55c8019d
Step 2/2 : RUN apt-get install nodejs
 ---> Running in 58200129772d
/bin/sh: apt-get: not found

The /bin/sh -c apt-get install nodejs command returned a non-zero code: 127.

3. ENV (https://docs.docker.com/engine/reference/builder/#env): ENV defines environment variables that will persist and be set prior to invoking your software in the container image. These are also set while creating the container image, which may cause surprising effects. If you need an environment variable set for a specific RUN command, for example, it is probably better to define it with a single RUN command rather than using the ENV command. For example, using ENV DEBIAN_FRONTEND non-interactive may confuse using a later RUN apt-get install … command on a Debian-based image. In the case where you want to enable that for a specific RUN command, you can do so by temporarily adding the environment variable in front of the single RUN command. For example:

RUN DEBIAN_FRONTEND=noninteractive apt-get install -y ...

4. COPY (https://docs.docker.com/engine/reference/builder/#copy): COPY (or the ADD command) is how you add your own local files into the container. This is often the most effective way to copy your code into the container image to run. You can copy an entire directory, or a single file. Along with the RUN command, this is likely going to be how you do most of the work of creating a container image with your code.

5. WORKDIR (https://docs.docker.com/engine/reference/builder/#workdir): WORKDIR makes a local directory and then makes that directory the base for all further commands (RUN, COPY, and so on). It can be extraordinarily convenient for RUN commands that expect to be run from a local or relative directory, such as installation tools such as Node.js npm.

6. LABEL (https://docs.docker.com/engine/reference/builder/#label): LABEL adds values that are visible to docker inspect and are generally used as references for who is responsible or what is within a container. The MAINTAINER command was very common earlier, but it has been replaced with the LABEL command. Labels are built on base images and are additive, so any labels you add will be included with labels from a base image you're using.

7. CMD (https://docs.docker.com/engine/reference/builder/#cmd) and ENTRYPOINT (https://docs.docker.com/engine/reference/builder/#entrypoint): CMD (and the ENTRYPOINT command) is how you specify what to run when someone runs your container. The most common format is a JSON array, where the first element is the command to be invoked, and the second and later elements are arguments to that command. CMD and ENTRYPOINT were made to be used either individually, in which case you use either CMD or ENTRYPOINT to specify the executable to run and all arguments, or together, in which case ENTRYPOINT should be just the executable and CMD should be the arguments for that executable.