Introduction
Docker images offer a convenient way to package an app and its dependencies for easy testing, sharing, and deployment of containers. The most common image creation method involves Dockerfile, a file with the instructions used by Docker to build a container image.
In this tutorial, learn how to create a Docker image from a Dockerfile.
Prerequisites
- Command-line access.
- Administrative privileges on the system.
- Docker installed.
What Is Dockerfile?
A Dockerfile is a file with a set of commands that specify how to build a Docker image. When a user executes the docker build command in a directory containing a Dockerfile, Docker runs the specified commands and creates a custom image on the local system.
Dockerfile commands have a wide range of purposes. Use them to:
- Install application dependencies.
- Specify the container environment.
- Set up application directories.
- Define runtime configuration.
- Provide image metadata.
Create Docker Image from Dockerfile
Note: If you are starting with Docker, read our beginner tutorials to learn more about Docker container management and basic Docker commands.
Follow the steps below to create a Dockerfile, build the image, and test it with Docker.
Step 1: Create Project Directory
Creating a Docker image with Dockerfile requires setting up a project directory. The directory contains the Dockerfile and stores all other files involved in building the image.
Create a directory by opening the Terminal and using the mkdir command:
mkdir <directory>Replace <directory> with the name of the project.
Step 2: Create Dockerfile
The contents of a Dockerfile depend on the image that it describes. The section below explains how to create a Dockerfile and provides a simple example to illustrate the procedure:
1. Navigate to the project directory:
cd <directory>2. Create a Dockerfile using a text editor of your choice. This article uses Nano:
nano Dockerfile3. Add the instructions for image building. For example, the code below creates a simple Docker image that uses Ubuntu as a base, runs the apt command to update the repositories, and executes an echo command that prints the words Hello World in the output:
FROM ubuntu
MAINTAINER test-user
RUN apt update
CMD ["echo", "Hello World"]
The following table contains a list of commands frequently present in a Dockerfile:
| Command Syntax | Description |
|---|---|
FROM <image> | Lets the user specify an existing image as a base for the creation of the custom image. To create an image from scratch, use FROM scratch. |
MAINTAINER <name> | Lists the image maintainer. |
RUN <command> | Specifies the commands running inside a container at build time. |
CMD <command> <argument>CMD ["<command>","<argument>"] | Defines the default executable for the Docker image. If the user does not provide command-line arguments for docker run, the container runs the process specified by the CMD command. |
ENTRYPOINT <command> <argument>ENTRYPOINT ["<command>","<argument>"] | Defines a variable. The user can assign different values to the defined variables in the docker build command using the --build-arg <variable>=<value> syntax. |
LABEL <key>=<value> | Adds metadata to the image. |
ENV <key>=<value> | Sets environment variables for the build process. The variables also persist in the container. |
ARG <key>[=<default-value>] | Defines a variable. The user can assign different values to the defined variables in the docker build command using the --build-arg <variable>=<value> syntax. |
COPY <source-path> <destination-path> | Allows the user to copy files into the container. The files must be in the Dockerfile directory or any subdirectory. |
Once you finish adding commands to the Dockerfile, save the file and exit.
Step 3: Build Docker Image
Use the following procedure to create a Docker image using the Dockerfile created in the previous step.
1. Run the following command to build a docker image, replacing <image> with an image name and <path> with the path to Dockerfile:
docker build -t <image> <path>The -t option allows the user to provide a name and (optionally) a tag for the new image. When executing the command from within the project directory, use (.) as the path:
docker build -t <image> .Docker reads the Dockerfile's contents and executes the commands in steps.
Once the container is created, the output shows the image has been built successfully.
Note: If you do not have sufficient permissions to issue Docker commands, the system outputs the Got permission denied while trying to connect to the Docker daemon message. Read our troubleshooting article to resolve the Permission Denied error in Docker.
2. Verify that the new image is in the list of local images by entering the following command:
docker imagesThe output shows the list of locally available images.
Step 4: Test Docker Image
To test the new image, use docker run to launch a new Docker container based on it:
docker run --name <container> <image>The example below uses the test-image image to create a container named test-container:
docker run --name test-container test-imageDocker creates a container and successfully executes the command listed in the image's Dockerfile.
Conclusion
This tutorial showed you how to create Docker images using Dockerfile. The guide explained some of the most common Dockerfile commands and provided instructions for building and testing the image.
Next, read how to prepare a Docker image for quick sharing using the docker save command.
