Format of a Dockefile
A dockerfile contains instructructions with arguments. Typically (but not necessarily), these arguements are written in uppercase letters.
INSTRUCTION arguments
With the execption of
ARG, a Dockefile must begin with a
FROM instruction (which specifies the
parent image from which a new image is built).
Dockerfiles allow
comments: they look similar to those in shell script,
Python or
PowerShell: they start with a
# and continue to the end of the line. However, only white spaces are allowed to the left side of the
# symbol.
Parser directives look like a special form of comments:
# directive=value
Instructions
ADD | Add local or remote files and directories. |
ARG | Use build-time variables. |
CMD | Specify the default command (or arguments executable defined with ENTRYPOINT) to be executed when the container is run. Compare with RUN |
COPY | Copy files and directories. |
ENTRYPOINT | Specify default executable (default seems to be ["/bin/sh", "-c"]) |
ENV | Set environment variables. |
EXPOSE | Describe which ports your application is listening on. Used in conjunction with the -P option of docker run. |
FROM | Create a new build stage from a base image. |
HEALTHCHECK | Check a container's health on startup. |
LABEL | Add metadata to an image. |
MAINTAINER | Specify the author of an image. Deprecated in favor of LABEL. |
ONBUILD | Specify instructions which are triggered then this image is used when building another image. |
RUN | Execute commands at build time. Compare with CMD |
SHELL | Set the default shell of an image. |
STOPSIGNAL | Specify the system call signal for exiting a container. |
USER | Set user and group ID. |
VOLUME | Create volume mounts. |
WORKDIR | Change working directory. |
FROM
FROM initializes a new build stage and sets the Base Image for subsequent instruction.
FROM <image>
# or
FROM <image> AS <name>
# or
FROM <image>[@<digest>] [AS <name>]
Using ARG:
ARG env=prod
FROM im:${env}
Using --platform:
FROM --platform=linux/arm64 …
…
FROM --platform=linux/amd64 …
…
ARG
ARG defines a variable whose value can be set and used when building the image.
In contrast,
ENV variables are used while a container of an image is running (see
ARG vs ENV).
ARG varname
Predefined ARG variables are: HTTP_PROXY, HTTPS_PROXY, FTP_PROXY and NO_PROXY. These variables are also available in a lowercase version.
COPY / ADD
COPY and ADD copy files and directories from outside a container into the container.
Paths are interpreted as relative to the source of the context of the build.
# source destination
# ---------- -----------
COPY README.txt /dev
COPY *.cs /dev/src
# source destination
# ---------- -----------
ADD README.txt /dev
ADD *.cs /dev/src
Docker on
Linux additionally has the
--chown parameter to specify a owning
user and a
group for the copied file:
ADD --chown=rene:dev *.cs /dev/src
CMD
CMD provides defaults for the resulting container.
At most one CMD instruction is allowed in a Dockerfile.
The specified command is executed as user and group specified with the
USER directive.
ENV
In contrast, the value of a variable being set with
ARG is available when a container is built (see
ARG vs ENV).
ENV version=4.2
ENTRYPOINT
ENTRYPOINT configures a container that will run as an executable.
Both,
CMD and
ENTRYPOINT define the commands that will be executed when running a container.
The specified command is executed as user and group specified with the
USER directive.
EXPOSE
EXPOSE documents a
TCP/IP (default) or UDP port for a container.
When running the
container, this or these ports are published with the
-P command line option in
docker run.
EXPOSE 80 # TCP/IP
EXPOSE 80/tcp
EXPOSE 67/udp
LABEL
LABEL adds metadata as a key/value pair to an image.
LABEL version=42.0
LABLE description=Hello world
RUN
Executes a command in the current image and commits the result.
The committed result is used as next «current image» in the next step.
# shell form: executed using /bin/sh -c command (Linux) or cmd.exe /s /c command
RUN <command>
# «Other» form:
RUN ["executable", "argument-one", "argument-two", …]
The specified command is executed as user and group specified with the
USER directive.
SHELL
SHELL allows to override the default shell (/bin/sh -c, cmd.exe /s /c).
SHELL ["powershell", "-command"]
RUN powershell-cmdLet
USER
USER controls which user and group will be running the commands that were specified with
RUN,
CMD and
ENTRYPOINT.
WORKDIR
WORKDIR sets the directory for subsequent
RUN,
CMD,
ENTRYPOINT,
COPY and
ADD commands.
WORKDIR /dev/src