Docker tutorial (2): Dockerfile

Hello, I am watching the mountains.

This article comes from the translation invitation of Concurrent Programming Network, and the translation is the second article in the "Docker Tutorial" by Jakob Jenkov .

Dockerfile contains a set of instructions on how to build a Docker image docker build. You can build a Docker image by executing the Dockerfile file with commands. This article describes how to write a Dockerfile and build a Docker image.

Benefits of Dockerfile

The Dockerfile file explains in written form how to build a Docker image, which usually contains the following content:

First, you need a basic Docker image, and build your own Docker image on this basic Docker image.
A set of tools and applications that need to be installed in the Docker image.
A set of files (such as configuration files) that need to be copied to the Docker image.
May need to open the network (TPC/UDP) port in the firewall or others.
and so on. . .

First of all, in the Dockerfile file to explain these in written form, it means that we do not need to specifically remember how the application is installed, including the operating system requirements, the applications that need to be installed, the files that need to be assigned, the network ports that need to be opened, etc. These contents are recorded in the Dockerfile.

In addition, by building a Docker image through a Dockerfile file, we don't need to manually perform these tedious, repetitive and error-prone tasks. Docker will do these things automatically, simple, fast, and not easy to make mistakes.

Third, it is easy for us to share the Dockerfile with others, and they can build the Docker image by themselves.

Fourth, the Dockerfile is easy to store in a version controller such as Git, so that you can track the change records of the Dockerfile (server, application configuration). The version controller can also make it easy for people to collaborate, such as on Dockerfile, and share Dockerfile.

Dockerfile structure

Dockerfile contains a set of instructions, each of which consists of a command and parameters, similar to a command-line executable file. Here is a simple example of a Dockerfile:

# 基础镜像
FROM ubuntu:latest

# 这里可以有更多安装软件和复制文件到镜像中的说明。
COPY    /myapp/target/myapp.jar    /myapp/myapp.jar

# 在Docker容器中执行的命令。
CMD echo Starting Docker Container

Docker base image

A Docker image is composed of layers, and each layer adds some content to the final Docker image. Each layer is actually a separate Docker image, so the Docker image is composed of one or more layer images, and we can add our own layers on top of it.

When specifying your own Docker image through a Dockerfile, you usually start with a Docker base image. This is another Docker image on which you can build your own Docker image. This Docker base image itself may also contain multiple layers and is built on top of another base image.

We can use Fromcommands to specify the Docker image as the base image in the Dockerfile, as described in the next section.

MAINTAINER

MAINTAINERThe command is used to indicate who is maintaining the Dockerfile. such as:

MAINTAINER   Joe Blocks <[email protected]>

MAINTAINERCommands are not commonly used, because this type of information is stored in Git or elsewhere.

FROM

FROMThe command is used to specify the Docker base image. If you start from the original Linux image, you can use the following command:

# 基础镜像
FROM ubuntu:latest

CMD

CMDThe command is used to specify the command that needs to be executed to start the Docker container. The container is a Docker image built based on this Dockerfile. The following are some examples of Dockerfile CMD:

CMD echo Docker container started.

In this example, the line of text "Docker container started" is printed.

The next CMDexample is to start a java application:

CMD java -cp /myapp/myapp.jar com.jenkov.myapp.MainClass arg1 arg2 arg3

COPY

COPYThe command copies one or more files from the host (the machine that builds the Docker image from the Dockerfile file) to the Docker image. The contents that can be copied include files or directories. The following is an example:

COPY    /myapp/target/myapp.jar    /myapp/myapp.jar

This example is to copy the host's /myapp/target/myapp.jar file to the Docker's ongoing /myapp/myapp.jar file. The first parameter is the host path (where it comes from), and the second parameter is the path (where to go) of the Docker image.

We can also copy a directory to the Docker image, such as:

COPY    /myapp/config/prod    /myapp/config

This example is to copy the /myapp/config/prod directory of the host to the /myapp/config directory in the Docker image.

We can also copy multiple files to a directory in the Docker image, such as:

COPY    /myapp/config/prod/conf1.cfg   /myapp/config/prod/conf2.cfg   /myapp/config/

This example is to copy the /myapp/config/prod/conf1.cfg file and /myapp/conig/prod/conf2.cfg file of the host to the /myapp/config/ directory in the Docker image. Note that the target directory must end with / (slash) to work.

ADD

ADDCommands COPYwork in the same way as commands, with some minor differences:

ADDCommands can copy and extract the TAR file to the Docker image.
ADDCommands can download files via HTTP and copy them to the Docker image.

Here are some examples:

ADD    myapp.tar    /myapp/

This example is to decompress and extract the specified TAR file to the /myapp/ directory of the Docker image.

Here is another example:

ADD    http://jenkov.com/myapp.jar    /myapp/

ENV

ENVThe command is to set environment variables in the Docker image. This environment variable can be used to CMDcommand to start the application inside the Docker image. for example:

ENV    MY_VAR   123

This example sets the environment variable MY_VARto the value 123.

RUN

RUNYou can execute command-line instructions in the Docker image. The execution time is during the Docker image building process, so the RUNcommand will only be executed once. RUNCommands can be used to install applications, extract files, or other command-line functions in the Docker image. These operations only need to be performed once for the subsequent use of the Docker image.

RUN apt-get install some-needed-app

ARG

ARGThe command allows to define a parameter, which can be passed to Docker through command parameters when building a Docker image through a Dockerfile. such as:

ARG tcpPort

When executing a docker buildcommand to execute a Dockerfile to build a Docker image, you can specify tcpPortparameters, such as:

docker build --build-arg tcpPort=8080 .

Note that the --build-arglatter tcpPort=8080is to set tcpPortthe value of the parameter to 8080.

We can ARGdefine multiple parameters through multiple commands, for example:

ARG tcpPort
ARG useTls

When building a Docker image, you must provide values for all build parameters. [Translator’s Note, before version 1.13, an error will be reported if no value is provided, after version 1.13, an error will not be reported if no value is provided, but a warning will pop up]. for example:

docker build --build-arg tcpPort=8080 --build-arg useTls=true .

We can ARGset the default value. When building the Docker image, if the parameter value is not specified, the default value will be used. for example:

ARG tcpPort=8080
ARG useTls=true

If tcpPortand useTlswhen the image generating Docker, parameters are not set, the default value 8080, and true.

ARGThe declared parameters are usually quoted elsewhere in the Dockerfile, such as:

ARG tcpPort=8080
ARG useTls=true

CMD start-my-server.sh -port ${tcpPort} -tls ${useTls}

Note: two references ${tcpPort}and ${useTls}references name tcpPortand useTlsboth ARGdeclared parameters.

docker build --build-arg tcpPort=8080

WORKDIR

WORKDIRThe command specifies the working directory in the Docker image, and the working directory will WORKDIRtake effect for all commands after the command. For example:

WORKDIR    /java/jdk/bin

EXPOSE

EXPOSEThe command will open the network port in the Docker container to the outside world. For example, if the Docker container runs a web server, then the web server may need to open port 80 so that the client can connect to it. for example:

EXPOSE   8080

We can also specify the communication protocol to open the port, such as UDP and TCP. The following is an example of setting allowed communication protocol:

EXPOSE   8080/tcp 9999/udp

If no protocol is specified, the TCP protocol will be assumed by default.

VOLUME

VOLUMEThe command will create a directory in the Docker image, which can be mounted on the Docker host. In other words, you can create a directory in the Docker image, for example /data, this directory can be mounted on the Docker host's /container-data/container1directory later . After the mount is successful, the container will start. The following is an example of using VOLUMEcommands to define the mount directory in the Dockerfile:

VOLUME   /data

ENTRYPOINT

ENTRYPOINTThe command provides an entry point for starting the Docker container from the Docker image, and the entry point is the application or command executed when the Docker container is started. Thus, ENTRYPOINTand CMDworks like, except that, using the ENTRYPOINTtime, when ENTRYPOINTthe application execution is completed, the container will be closed Docker. Therefore, ENTRYPOINTthe Docker image itself becomes an executable command, which can be started and closed after completion. The following is ENTRYPOINTan example:

ENTRYPOINT java -cp /apps/myapp/myapp.jar com.jenkov.myapp.Main

This example will execute the main class of the Java application when the container starts, com.jenkov.myapp.Mainand when the application is closed, the Docker container will also be closed.

HEALTHCHECK

HEALTHCHECKCommands can periodically perform health checks to monitor the health of applications running in Docker containers. If the command returns 0, Docker will consider the application and container to be normal. If the command returns 1, Docker will consider the application and container to be abnormal. Examples are as follows:

HEALTHCHECK java -cp /apps/myapp/healthcheck.jar com.jenkov.myapp.HealthCheck https://localhost/healthcheck

In this example, the java application's com.jenkov.myapp.HealthCheckhealth check command is used. We can use any meaningful health check command.

Health check interval

By default, Docker executes HEALTHCHECKcommands every 30 seconds . If you want to modify the time interval, we can customize the time. Through --intervalparameters, you can specify the check interval for the health check. Here is an HEALTHCHECKexample of setting the interval to 60 seconds:

HEALTHCHECK --interval=60s java -cp /apps/myapp/healthcheck.jar com.jenkov.myapp.HealthCheck https://localhost/healthcheck

Health check start time

By default, Docker will immediately check the monitoring status of the Docker container. However, some applications may take some time to start, so it makes sense to perform a health check only after a certain period of time. We can use --start-periodparameters to set the start time of the health check. The following is an example of setting the health check to 5 minutes. Before Docker starts the health check, a startup time of 300 seconds (5 minutes) is provided for the container and the application:

HEALTHCHECK --start-period=300s java -cp /apps/myapp/healthcheck.jar com.jenkov.myapp.HealthCheck https://localhost/healthcheck

Health check timeout

The health check is likely to time out. If the HEALTCHECKcommand needs to exceed the given time limit to complete, Docker will consider the health check to time out. You can use --timeoutparameters to set the timeout period. The following is an example of setting the timeout period to 5 seconds:

HEALTHCHECK --timeout=5s java -cp /apps/myapp/healthcheck.jar com.jenkov.myapp.HealthCheck https://localhost/healthcheck

Note that if the health check times out, Docker will also consider the container to be unhealthy.

Number of repetitions of health check

If the HEALTHCHECKcommand execution fails, it may be that the result returns 1, or the execution times out. Docker will retry the HEALTHCHECKcommand 3 times before determining that the container is unhealthy to check whether the Docker container returns to a healthy state. You can --retriesset the number of retries. The following is an example of setting the number of retries to 5:

HEALTHCHECK --retries=5 java -cp /apps/myapp/healthcheck.jar com.jenkov.myapp.HealthCheck https://localhost/healthcheck