How to build docker image

Create a base image

Estimated reading time: 3 minutes

Most Dockerfiles start from a parent image. If you need to completely control the contents of your image, you might need to create a base image instead. Here’s the difference:

A parent image is the image that your image is based on. It refers to the contents of the FROM directive in the Dockerfile. Each subsequent declaration in the Dockerfile modifies this parent image. Most Dockerfiles start from a parent image, rather than a base image. However, the terms are sometimes used interchangeably.

A base image has FROM scratch in its Dockerfile.

This topic shows you several ways to create a base image. The specific process will depend heavily on the Linux distribution you want to package. We have some examples below, and you are encouraged to submit pull requests to contribute new ones.

Create a full image using tar

In general, start with a working machine that is running the distribution you’d like to package as a parent image, though that is not required for some tools like Debian’s Debootstrap, which you can also use to build Ubuntu images.

It can be as simple as this to create an Ubuntu parent image:

There are more example scripts for creating parent images in the Docker GitHub repository.

Create a simple parent image using scratch

Note: Because Docker Desktop for Mac and Docker Desktop for Windows use a Linux VM, you need a Linux binary, rather than a Mac or Windows binary. You can use a Docker container to build it:

To run your new image, use the docker run command:

This example creates the hello-world image used in the tutorials. If you want to test it out, you can clone the image repo.

More resources

Overview of Docker Build

Estimated reading time: 3 minutes

Docker Build is one of Docker Engine’s most used features. Whenever you are creating an image you are using Docker Build. Build is a key part of your software development life cycle allowing you to package and bundle your code and ship it anywhere.

Engine uses a client-server architecture and is composed of multiple components and tools. The most common method of executing a build is by issuing a docker build command from the Docker CLI. The CLI sends the request to Docker Engine which, in turn, executes your build.

There are now two components in Engine that can be used to create the build. Starting with the 18.09 release, Engine is shipped with Moby BuildKit, the new component for executing your builds by default.

BuildKit is the backend evolution from the Legacy Builder, it comes with new and much improved functionality that can be powerful tools for improving your builds’ performance or reusability of your Dockerfiles, and it also introduces support for complex scenarios.

Docker Build features

Docker Build is way more than your docker build command and is not only about packaging your code, it’s a whole ecosystem of tools and features that support you not only with common workflow tasks but also provides you with support for more complex and advanced scenarios. Here’s an overview of all the use cases with which Build can support you:

Building your images

Packaging your software
Bundle and package your code to run anywhere, from your local Docker Desktop, to Docker Engine and Kubernetes on the cloud.
To get started with Build, see the Hello Build page.

Choosing a build driver
Run Buildx with different configurations depending on the scenario you are working on, regardless of whether you are using your local machine or a remote compute cluster, all from the comfort of your local working environment. For more information on drivers, see the drivers guide.

Optimizing builds with cache management
Improve build performance by using a persistent shared build cache to avoid repeating costly operations such as package installations, downloading files from the internet, or code build steps.

Creating build-once, run-anywhere with multi-platform builds Collaborate across platforms with one build artifact.
See Build multi-platform images.

Automating your builds

Customizing your Builds

Select your build output format
Choose from a variety of available output formats, to export any artifact you like from BuildKit, not just docker images.
See Set the export action for the build result.

Managing build secrets
Securely access protected repositories and resources at build time without leaking data into the final build or the cache.

Extending BuildKit

Custom syntax on Dockerfile
Use experimental versions of the Dockerfile frontend, or even just bring your own to BuildKit using the power of custom frontends.
See also the Syntax directive.

Sample application

Estimated reading time: 5 minutes

For the rest of this tutorial, we will be working with a simple todo list manager that is running in Node.js. If you’re not familiar with Node.js, don’t worry. No real JavaScript experience is needed.

At this point, your development team is quite small and you’re simply building an app to prove out your MVP (minimum viable product). You want to show how it works and what it’s capable of doing without needing to think about how it will work for a large team, multiple developers, etc.

Get the app

Before we can run the application, we need to get the application source code onto our machine. For real projects, you will typically clone the repo. But, for this tutorial, we have created a ZIP file containing the application.

Download the App contents from the getting-started repository. You can either pull the entire project or download it as a zip and extract the app folder out to get started with.

Once extracted, use your favorite code editor to open the project. If you’re in need of an editor, you can use Visual Studio Code. You should see the package.json and two subdirectories ( src and spec ).

Build the app’s container image

Create a file named Dockerfile in the same folder as the file package.json with the following contents.

This command used the Dockerfile to build a new container image. You might have noticed that a lot of “layers” were downloaded. This is because we instructed the builder that we wanted to start from the node:12-alpine image. But, since we didn’t have that on our machine, that image needed to be downloaded.

After the image was downloaded, we copied in our application and used yarn to install our application’s dependencies. The CMD directive specifies the default command to run when starting a container from this image.

Start an app container

Now that we have an image, let’s run the application. To do so, we will use the docker run command (remember that from earlier?).

Start your container using the docker run command and specify the name of the image we just created:

After a few seconds, open your web browser to http://localhost:3000. You should see our app.

Go ahead and add an item or two and see that it works as you expect. You can mark items as complete and remove items. Your frontend is successfully storing items in the backend. Pretty quick and easy, huh?

At this point, you should have a running todo list manager with a few items, all built by you. Now, let’s make a few changes and learn about managing our containers.

If you take a quick look at the Docker Dashboard, you should see your two containers running now (this tutorial and your freshly launched app container).

Recap

In this short section, we learned the very basics about building a container image and created a Dockerfile to do so. Once we built an image, we started the container and saw the running app.

Next, we’re going to make a modification to our app and learn how to update our running application with a new image. Along the way, we’ll learn a few other useful commands.

Hello Build

Estimated reading time: 7 minutes

Hello Build!

It all starts with a Dockerfile.

Dockerfiles are text files containing instructions. Dockerfiles adhere to a specific format and contain a set of instructions for which you can find a full reference in the Dockerfile reference.
Docker builds images by reading the instructions from a Dockerfile.

Docker images consist of read-only layers, each resulting from an instruction in the Dockerfile. Layers are stacked sequentially and each one is a delta representing the changes applied to the previous layer.

Dockerfile basics

A Dockerfile is a text file containing all necessary instructions needed to assemble your application into a Docker container image.

Here are the most common types of instructions:

Dockerfiles are crucial inputs for image builds and can facilitate automated, multi-layer image builds based on your unique configurations. Dockerfiles can start simple and grow with your needs and support images that require complex instructions.
For all the possible instructions, see the Dockerfile reference.

Example

Here’s a simple Dockerfile example to get you started with building images. We’ll take a simple “Hello World” Python Flask application, and bundle it into a Docker image that we can test locally or deploy anywhere!

Sample A
Let’s say we have the following in a hello.py file in our local directory:

If you test the example, make sure to copy over the indentation as well! For more information about this sample Flask application, check the Flask Quickstart page.

Sample B
Here’s a Dockerfile that Docker Build can use to create an image for our application:

This is our syntax directive. It pins the exact version of the dockerfile syntax we’re using. As a best practice, this should be the very first line in all our Dockerfiles as it informs Buildkit the right version of the Dockerfile to use. See also Syntax.

Initiated by a # like regular comments, this line is treated as a directive when you are using BuildKit (default), otherwise it is ignored.

# install app dependencies

Comments in dockerfiles begin with the # symbol. As your Dockerfile evolves, comments can be instrumental to document how your dockerfile works for any future readers and editors of the file.
See also the FROM instruction page in the Dockerfile reference.

This RUN instruction executes a shell command in the build context. A build’s context is the set of files located in the specified PATH or URL. In this example, our context is a full Ubuntu operating system, so we have access to its package manager, apt. The provided commands update our package lists and then, after that succeeds, installs python3 and pip, the package manager for Python.
See also the RUN instruction page in the Dockerfile reference.

RUN pip install flask

This second RUN instruction requires that we’ve installed pip in the layer before. After applying the previous directive, we can use the pip command to install the flask web framework. This is the framework we’ve used to write our basic “Hello World” application from above, so to run it in Docker, we’ll need to make sure it’s installed.
See also the RUN instruction page in the Dockerfile reference.

This COPY instruction copies our hello.py file from the build’s context local directory into the root directory of our image. After this executes, we’ll end up with a file called /hello.py inside the image, with all the content of our local copy!
See also the COPY instruction page in the Dockerfile reference.

This ENV instruction sets a Linux environment variable we’ll need later. This is a flask-specific variable, that configures the command later used to run our hello.py application. Without this, flask wouldn’t know where to find our application to be able to run it.
See also the ENV instruction page in the Dockerfile reference.

This EXPOSE instruction marks that our final image has a service listening on port 8000. This isn’t required, but it is a good practice, as users and tools can use this to understand what your image does.
See also the EXPOSE instruction page in the Dockerfile reference.

This CMD instruction sets the command that is run when the user starts a container based on this image. In this case we’ll start the flask development server listening on all hosts on port 8000.
CMD instruction page in the Dockerfile reference.

Test the example

Go ahead and try this example in your local Docker installation or you can use Play with Docker that provides you with a temporary Docker instance on the cloud.

To test this example:

Create a file hello.py with the content of sample A.

Create a file named Dockerfile without an extension with the contents of sample B.

Breaking down the docker build command:

So, in accordance with the build command issued and how build context works, your Dockerfile and python app need to be on the same directory.

From your computer, open a browser and navigate to http://localhost:8000 or, if you’re using Play with Docker, click on Open Port.

Other resources

If you are interested in examples in other languages, such as GO, check out our language-specific guides in the Guides section.

Best practices for writing Dockerfiles

Estimated reading time: 33 minutes

This document covers recommended best practices and methods for building efficient images.

A Docker image consists of read-only layers each of which represents a Dockerfile instruction. The layers are stacked and each one is a delta of the changes from the previous layer. Consider this Dockerfile :

Each instruction creates one layer:

When you run an image and generate a container, you add a new writable layer (the “container layer”) on top of the underlying layers. All changes made to the running container, such as writing new files, modifying existing files, and deleting files, are written to this writable container layer.

For more on image layers (and how Docker builds and stores images), see About storage drivers.

General guidelines and recommendations

Create ephemeral containers

The image defined by your Dockerfile should generate containers that are as ephemeral as possible. By “ephemeral”, we mean that the container can be stopped and destroyed, then rebuilt and replaced with an absolute minimum set up and configuration.

Refer to Processes under The Twelve-factor App methodology to get a feel for the motivations of running containers in such a stateless fashion.

Understand build context

Inadvertently including files that are not necessary for building an image results in a larger build context and larger image size. This can increase the time to build the image, time to pull and push it, and the container runtime size. To see how big your build context is, look for a message like this when building your Dockerfile :

Pipe Dockerfile through stdin

Docker has the ability to build images by piping Dockerfile through stdin with a local or remote build context. Piping a Dockerfile through stdin can be useful to perform one-off builds without writing a Dockerfile to disk, or in situations where the Dockerfile is generated, and should not persist afterwards.

The examples in this section use here documents for convenience, but any method to provide the Dockerfile on stdin can be used.

For example, the following commands are equivalent:

You can substitute the examples with your preferred approach, or the approach that best fits your use-case.

Build an image using a Dockerfile from stdin, without sending build context

Omitting the build context can be useful in situations where your Dockerfile does not require files to be copied into the image, and improves the build-speed, as no files are sent to the daemon.

Note: Attempting to build a Dockerfile that uses COPY or ADD will fail if this syntax is used. The following example illustrates this:

Build from a local build context, using a Dockerfile from stdin

Build from a remote build context, using a Dockerfile from stdin

When building an image using a remote Git repository as build context, Docker performs a git clone of the repository on the local machine, and sends those files as build context to the daemon. This feature requires git to be installed on the host where you run the docker build command.

Use multi-stage builds

Multi-stage builds allow you to drastically reduce the size of your final image, without struggling to reduce the number of intermediate layers and files.

Because an image is built during the final stage of the build process, you can minimize image layers by leveraging build cache.

For example, if your build contains several layers, you can order them from the less frequently changed (to ensure the build cache is reusable) to the more frequently changed:

Install tools you need to build your application

Install or update library dependencies

Generate your application

A Dockerfile for a Go application could look like:

Don’t install unnecessary packages

To reduce complexity, dependencies, file sizes, and build times, avoid installing extra or unnecessary packages just because they might be “nice to have.” For example, you don’t need to include a text editor in a database image.

Decouple applications

Each container should have only one concern. Decoupling applications into multiple containers makes it easier to scale horizontally and reuse containers. For instance, a web application stack might consist of three separate containers, each with its own unique image, to manage the web application, database, and an in-memory cache in a decoupled manner.

Limiting each container to one process is a good rule of thumb, but it is not a hard and fast rule. For example, not only can containers be spawned with an init process, some programs might spawn additional processes of their own accord. For instance, Celery can spawn multiple worker processes, and Apache can create one process per request.

Use your best judgment to keep containers as clean and modular as possible. If containers depend on each other, you can use Docker container networks to ensure that these containers can communicate.

Minimize the number of layers

In older versions of Docker, it was important that you minimized the number of layers in your images to ensure they were performant. The following features were added to reduce this limitation:

Where possible, use multi-stage builds, and only copy the artifacts you need into the final image. This allows you to include tools and debug information in your intermediate build stages without increasing the size of the final image.

Sort multi-line arguments

Whenever possible, ease later changes by sorting multi-line arguments alphanumerically. This helps to avoid duplication of packages and make the list much easier to update. This also makes PRs a lot easier to read and review. Adding a space before a backslash ( \ ) helps as well.

Here’s an example from the buildpack-deps image:

Leverage build cache

Starting with a parent image that is already in the cache, the next instruction is compared against all child images derived from that base image to see if one of them was built using the exact same instruction. If not, the cache is invalidated.

In most cases, simply comparing the instruction in the Dockerfile with one of the child images is sufficient. However, certain instructions require more examination and explanation.

For the ADD and COPY instructions, the contents of the file(s) in the image are examined and a checksum is calculated for each file. The last-modified and last-accessed times of the file(s) are not considered in these checksums. During the cache lookup, the checksum is compared against the checksum in the existing images. If anything has changed in the file(s), such as the contents and metadata, then the cache is invalidated.

Once the cache is invalidated, all subsequent Dockerfile commands generate new images and the cache is not used.

Dockerfile instructions

Whenever possible, use current official images as the basis for your images. We recommend the Alpine image as it is tightly controlled and small in size (currently under 6 MB), while still being a full Linux distribution.

LABEL

You can add labels to your image to help organize images by project, record licensing information, to aid in automation, or for other reasons. For each label, add a line beginning with LABEL and with one or more key-value pairs. The following examples show the different acceptable formats. Explanatory comments are included inline.

Strings with spaces must be quoted or the spaces must be escaped. Inner quote characters ( » ), must also be escaped.

An image can have more than one label. Prior to Docker 1.10, it was recommended to combine all labels into a single LABEL instruction, to prevent extra layers from being created. This is no longer necessary, but combining labels is still supported.

The above can also be written as:

See Understanding object labels for guidelines about acceptable label keys and values. For information about querying labels, refer to the items related to filtering in Managing labels on objects. See also LABEL in the Dockerfile reference.

Split long or complex RUN statements on multiple lines separated with backslashes to make your Dockerfile more readable, understandable, and maintainable.

apt-get

Always combine RUN apt-get update with apt-get install in the same RUN statement. For example:

Using apt-get update alone in a RUN statement causes caching issues and subsequent apt-get install instructions fail. For example, say you have a Dockerfile:

After building the image, all layers are in the Docker cache. Suppose you later modify apt-get install by adding extra package:

Docker sees the initial and modified instructions as identical and reuses the cache from previous steps. As a result the apt-get update is not executed because the build uses the cached version. Because the apt-get update is not run, your build can potentially get an outdated version of the curl and nginx packages.

Version pinning forces the build to retrieve a particular version regardless of what’s in the cache. This technique can also reduce failures due to unanticipated changes in required packages.

Below is a well-formed RUN instruction that demonstrates all the apt-get recommendations.

Using pipes

Some RUN commands depend on the ability to pipe the output of one command into another, using the pipe character ( | ), as in the following example:

In cases such as the dash shell on Debian-based images, consider using the exec form of RUN to explicitly choose a shell that does support the pipefail option. For example:

EXPOSE

For external access, your users can execute docker run with a flag indicating how to map the specified port to the port of their choice. For container linking, Docker provides environment variables for the path from the recipient container back to the source (ie, MYSQL_PORT_3306_TCP ).

To make new software easier to run, you can use ENV to update the PATH environment variable for the software your container installs. For example, ENV PATH=/usr/local/nginx/bin:$PATH ensures that CMD [«nginx»] just works.

Lastly, ENV can also be used to set commonly used version numbers so that version bumps are easier to maintain, as seen in the following example:

Similar to having constant variables in a program (as opposed to hard-coding values), this approach lets you change a single ENV instruction to auto-magically bump the version of the software in your container.

Each ENV line creates a new intermediate layer, just like RUN commands. This means that even if you unset the environment variable in a future layer, it still persists in this layer and its value can be dumped. You can test this by creating a Dockerfile like the following, and then building it.

ADD or COPY

If you have multiple Dockerfile steps that use different files from your context, COPY them individually, rather than all at once. This ensures that each step’s build cache is only invalidated (forcing the step to be re-run) if the specifically required files change.

Because image size matters, using ADD to fetch packages from remote URLs is strongly discouraged; you should use curl or wget instead. That way you can delete the files you no longer need after they’ve been extracted and you don’t have to add another layer in your image. For example, you should avoid doing things like:

And instead, do something like:

ENTRYPOINT

The best use for ENTRYPOINT is to set the image’s main command, allowing that image to be run as though it was that command (and then use CMD as the default flags).

Let’s start with an example of an image for the command line tool s3cmd :

Now the image can be run like this to show the command’s help:

Or using the right parameters to execute a command:

This is useful because the image name can double as a reference to the binary as shown in the command above.

The ENTRYPOINT instruction can also be used in combination with a helper script, allowing it to function in a similar way to the command above, even when starting the tool may require more than one step.

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

This script uses the exec Bash command so that the final running application becomes the container’s PID 1. This allows the application to receive any Unix signals sent to the container. For more, see the ENTRYPOINT reference.

The helper script is copied into the container and run via ENTRYPOINT on container start:

This script allows the user to interact with Postgres in several ways.

It can simply start Postgres:

Or, it can be used to run Postgres and pass parameters to the server:

Lastly, it could also be used to start a totally different tool, such as Bash:

VOLUME

The VOLUME instruction should be used to expose any database storage area, configuration storage, or files/folders created by your docker container. You are strongly encouraged to use VOLUME for any mutable and/or user-serviceable parts of your image.

If a service can run without privileges, use USER to change to a non-root user. Start by creating the user and group in the Dockerfile with something like:

Users and groups in an image are assigned a non-deterministic UID/GID in that the “next” UID/GID is assigned regardless of image rebuilds. So, if it’s critical, you should assign an explicit UID/GID.

Lastly, to reduce layers and complexity, avoid switching USER back and forth frequently.

WORKDIR

ONBUILD

Examples of Docker Official Images

These Official Images have exemplary Dockerfile s: