Dockerfile Instructions and Syntax

17 Sep 2015

In my previous post we learnt about Docker basics and its installation process on a non-Linux system. We also learnt about Docker architecture and the terminology used while dealing with Docker. But what next?

All this knowledge is no good if can’t solve a real life problem.

We all know that Docker simplifies application deployment via containerization. But how does that happen, and how can you use Docker to deploy your own application quickly?

To understand this, we need to understand the image creation process and the steps to spawn a container from an image.

So, let’s start with the process of creating Docker images.

Dockerfile to Docker image to Docker container

A Docker image is a read-only template used to create and launch a Docker container.

A Docker image can be plain and simple Linux distro (known as base image) or fully-configured enterprise software install, ready to run. It all depends on the Dockerfile.

A Dockerfile is a text file with instructions written in a format understood by the Docker daemon (Docker daemon is one of the Docker components, that does the heavy-duty tasks of building, running, and distributing the Docker images, after getting commands from the Docker client). To create an image, you need to write your own Dockerfile. But don’t worry, there are only a handful of Dockerfile configuration options (called instructions), and they are very easy to understand. We’ll take a look at all the instructions later in this tutorial.

Coming back to images|: after you have your Dockerfile ready, you can execute docker build . from command prompt to create the corresponding image. Then run docker run <image-name> to create a container out of the image and execute it. Simple.

One interesting thing to note about Docker images is, they use the Union file system, allowing combination of different layers (operating system, host file system, dependencies, and so on) into a single coherent file system. This layered architecture makes addition or removal of content from the image as simple as adding or removing instructions from the Dockerfile. As you can imagine, this makes modification easy.

Dockerfile Instructions

Let’s now take a look at various Dockerfile instructions and their usage.


This instruction is used to set the base image for subsequent instructions. It is mandatory to set this in the first line of a Dockerfile. You can use it any number of times though.


FROM ubuntu


This is a non-executable instruction used to indicate the author of the Dockerfile.




This instruction lets you execute a command on top of an existing layer and create a new layer with the results of command execution.

For example, if there is a pre-condition to install PHP before running an application, you can run appropriate commands to install PHP on top of base image (say Ubuntu) like this:

FROM ubuntu
RUN apt-get update update apt-get install php5


The major difference between CMD and RUN is that CMD doesn’t execute anything during the build time. It just specifies the intended command for the image. Whereas RUN actually executes the command during build time.

Note: there can be only one CMD instruction in a Dockerfile, if you add more, only the last one takes effect.


CMD "echo" "Hello World!"


You can assign metadata in the form of key-value pairs to the image using this instruction. It is important to notice that each LABEL instruction creates a new layer in the image, so it is best to use as few LABEL instructions as possible.


LABEL version="1.0" description="This is a sample desc"


While running your service in the container you may want your container to listen on specified ports. The EXPOSE instruction helps you do this.




This instruction can be used to set the environment variables in the container.


ENV var_home="/var/etc"


This instruction is used to copy files and directories from a specified source to a destination (in the file system of the container).


COPY preconditions.txt /usr/temp


This instruction is similar to the COPY instruction with few added features like remote URL support in the source field and local-only tar extraction. But if you don’t need a extra features, it is suggested to use COPY as it is more readable.


ADD /usr/src


You can use this instruction to set the primary command for the image.

For example, if you have installed only one application in your image and want it to run whenever the image is executed, ENTRYPOINT is the instruction for you.

Note: arguments are optional, and you can pass them during the runtime with something like docker run <image-name>.

Also, all the elements specified using CMD will be overridden, except the arguments. They will be passed to the command specified in ENTRYPOINT.


CMD "Hello World!"


You can use the VOLUME instruction to enable access to a location on the host system from a container. Just pass the path of the location to be accessed.


VOLUME /data


This is used to set the UID (or username) to use when running the image.


USER daemon


This is used to set the currently active directory for other instructions such as RUN, CMD, ENTRYPOINT, COPY and ADD.

Note that if relative path is provided, the next WORKDIR instruction will take it as relative to the path of previous WORKDIR instruction.


RUN pwd

This will output the path as /user/home.


This instruction adds a trigger instruction to be executed when the image is used as the base for some other image. It behaves as if a RUN instruction is inserted immediately after the FROM instruction of the downstream Dockerfile. This is typically helpful in cases where you need a static base image with a dynamic config value that changes whenever a new image has to be built (on top of the base image).


ONBUILD RUN rm -rf /usr/temp

Dockerfile Syntax

Now that we have a clear idea of Dockerfile instructions, lets check out the instruction structure (i.e. the syntax) to be followed while writing a Dockerfile.

There are just two main line blocks in a Dockerfile: comments and instructions.

In the general case:

# This is the comment block
Instruction [arguments]

For example:

# Display "Hello World!"
RUN echo "Hello World!"

While writing a Dockerfile, follow the simple rule of listing all the instructions successively, inside a plain text file and name it as Dockerfile. Of course, these instructions should be written in the order to be executed.

Remember: the first instruction in a Dockerfile should always be the FROM instruction. This is to make sure the base is ready before adding layers to the image.


Dockerfiles provide a simple and easy way to create your own Docker images, with very minimal programming effort required.

In this post, we learnt about Docker image and container execution basics, along with the various Dockerfile instructions available, and the way to use them. We also learnt about the simple Dockerfile syntax.

In the next post, we’ll take a look at a sample Dockerfile and analyze its instructions to get a feel of how to create efficient Docker images. We will also learn about the Docker hub and the steps needed to share your own images with the world.

Posted in Docker, Overview

triangle square circle

Did you enjoy this post?