Expose Movie

[Jackie Bullinger]

Dockercan build images automatically by reading the instructions from aDockerfile. A Dockerfile is a text document that contains all the commands auser could call on the command line to assemble an image. This page describesthe commands you can use in a Dockerfile.

Docker runs instructions in a Dockerfile in order. A Dockerfile mustbegin with a FROM instruction. This may be afterparserdirectives,comments, and globally scopedARGs. The FROM instruction specifies theparentimage from which you arebuilding. FROM may only be preceded by one or more ARG instructions, whichdeclare arguments that are used in FROM lines in the Dockerfile.

For backward compatibility, leading whitespace before comments (#) andinstructions (such as RUN) are ignored, but discouraged. Leading whitespaceis not preserved in these cases, and the following examples are thereforeequivalent:

Parser directives are optional, and affect the way in which subsequent linesin a Dockerfile are handled. Parser directives don't add layers to the build,and don't show up as build steps. Parser directives are written as aspecial type of comment in the form # directive=value. A single directivemay only be used once.

Once a comment, empty line or builder instruction has been processed, BuildKitno longer looks for parser directives. Instead it treats anything formattedas a parser directive as a comment and doesn't attempt to validate if it mightbe a parser directive. Therefore, all parser directives must be at thetop of a Dockerfile.

Parser directives aren't case-sensitive, but they're lowercase by convention.It's also conventional to include a blank line following any parser directives.Line continuation characters aren't supported in parser directives.

Use the syntax parser directive to declare the Dockerfile syntax version touse for the build. If unspecified, BuildKit uses a bundled version of theDockerfile frontend. Declaring a syntax version lets you automatically use thelatest Dockerfile version without having to upgrade BuildKit or Docker Engine,or even use a custom Dockerfile implementation.

The escape character is used both to escape characters in a line, and toescape a newline. This allows a Dockerfile instruction tospan multiple lines. Note that regardless of whether the escape parserdirective is included in a Dockerfile, escaping is not performed ina RUN command, except at the end of a line.

Consider the following example which would fail in a non-obvious way onWindows. The second \ at the end of the second line would be interpreted as anescape for the newline, instead of a target of the escape from the first \.Similarly, the \ at the end of the third line would, assuming it was actuallyhandled as an instruction, cause it be treated as a line continuation. The resultof this Dockerfile is that second and third lines are considered a singleinstruction:

One solution to the above would be to use / as the target of both the COPYinstruction, and dir. However, this syntax is, at best, confusing as it is notnatural for paths on Windows, and at worst, error prone as not all commands onWindows support / as the path separator.

Environment variables (declared withthe ENV statement) can also beused in certain instructions as variables to be interpreted by theDockerfile. Escapes are also handled for including variable-like syntaxinto a statement literally.

You can also use environment variables with RUN, CMD, and ENTRYPOINTinstructions, but in those cases the variable substitution is handled by thecommand shell, not the builder. Note that instructions using the exec formdon't invoke a command shell automatically. SeeVariablesubstitution.

Environment variable substitution use the same value for each variablethroughout the entire instruction. Changing the value of a variable only takeseffect in subsequent instructions. Consider the following example:

The exec form makes it possible to avoid shell string munging, and to invokecommands using a specific command shell, or any other executable. It uses aJSON array syntax, where each element in the array is a command, flag, orargument.

Using the exec form doesn't automatically invoke a command shell. This meansthat normal shell processing, such as variable substitution, doesn't happen.For example, RUN [ "echo", "$HOME" ] won't handle variable substitution for$HOME.

If you want shell processing then either use the shell form or execute a shelldirectly with the exec form, for example: RUN [ "sh", "-c", "echo $HOME" ].When using the exec form and executing a shell directly, as in the case for theshell form, it's the shell that's doing the environment variable substitution,not the builder.

In exec form, you must escape backslashes. This is particularly relevant onWindows where the backslash is the path separator. The following line wouldotherwise be treated as shell form due to not being valid JSON, and fail in anunexpected way:

Unlike the exec form, instructions using the shell form always use a commandshell. The shell form doesn't use the JSON array format, instead it's a regularstring. The shell form string lets you escape newlines using theescapecharacter (backslash by default) to continue a single instructiononto the next line. This makes it easier to use with longer commands, becauseit lets you split them up into multiple lines. For example, consider these twolines:

The optional --platform flag can be used to specify the platform of the imagein case FROM references a multi-platform image. For example, linux/amd64,linux/arm64, or windows/amd64. By default, the target platform of the buildrequest is used. Global build arguments can be used in the value of this flag,for exampleautomatic platform ARGsallow you to force a stage to native build platform (--platform=$BUILDPLATFORM),and use it to cross-compile to the target platform inside the stage.

An ARG declared before a FROM is outside of a build stage, so itcan't be used in any instruction after a FROM. To use the default value ofan ARG declared before the first FROM use an ARG instruction withouta value inside of a build stage:

The cache for RUN instructions isn't invalidated automatically duringthe next build. The cache for an instruction likeRUN apt-get dist-upgrade -y will be reused during the next build. Thecache for RUN instructions can be invalidated by using the --no-cacheflag, for example docker build --no-cache.

Contents of the cache directories persists between builder invocations withoutinvalidating the instruction cache. Cache mounts should only be used for betterperformance. Your build should work with any contents of the cache directory asanother build may overwrite the files or GC may clean it if more storage spaceis needed.

Apt needs exclusive access to its data, so the caches use the optionsharing=locked, which will make sure multiple parallel builds usingthe same cache mount will wait for each other and not access the samecache files at the same time. You could also use sharing=private ifyou prefer to have each build create another cache directory in thiscase.

The use of --network=host is protected by the network.host entitlement,which needs to be enabled when starting the buildkitd daemon with--allow-insecure-entitlement network.host flag or inbuildkitd config,and for a build request with--allow network.host flag.

The default security mode is sandbox.With --security=insecure, the builder runs the command without sandbox in insecuremode, which allows to run flows requiring elevated privileges (e.g. containerd).This is equivalent to running docker run --privileged.

In order to access this feature, entitlement security.insecure should beenabled when starting the buildkitd daemon with--allow-insecure-entitlement security.insecure flag or inbuildkitd config,and for a build request with--allow security.insecure flag.

The purpose of a CMD is to provide defaults for an executing container. Thesedefaults can include an executable, or they can omit the executable, in whichcase you must specify an ENTRYPOINT instruction as well.

If you would like your container to run the same executable every time, thenyou should consider using ENTRYPOINT in combination with CMD. SeeENTRYPOINT. If the user specifies arguments to docker runthen they will override the default specified in CMD, but still use thedefault ENTRYPOINT.

The LABEL instruction adds metadata to an image. A LABEL is akey-value pair. To include spaces within a LABEL value, use quotes andbackslashes as you would in command-line parsing. A few usage examples:

An image can have more than one label. You can specify multiple labels on asingle line. Prior to Docker 1.10, this decreased the size of the final image,but this is no longer the case. You may still choose to specify multiple labelsin a single instruction, in one of the following two ways:

Be sure to use double quotes and not single quotes. Particularly when you areusing string interpolation (e.g. LABEL example="foo-$ENV_VAR"), singlequotes will take the string as is without unpacking the variable's value.

Labels included in base or parent images (images in the FROM line) areinherited by your image. If a label already exists but with a different value,the most-recently-applied value overrides any previously-set value.

The MAINTAINER instruction sets the Author field of the generated images.The LABEL instruction is a much more flexible version of this and you should useit instead, as it enables setting any metadata you require, and can be viewedeasily, for example with docker inspect. To set a label corresponding to theMAINTAINER field you could use:

The EXPOSE instruction informs Docker that the container listens on thespecified network ports at runtime. You can specify whether the port listens onTCP or UDP, and the default is TCP if you don't specify a protocol.

The EXPOSE instruction doesn't actually publish the port. It functions as atype of documentation between the person who builds the image and the person whoruns the container, about which ports are intended to be published. Topublish the port when running the container, use the -p flag on docker runto publish and map one or more ports, or the -P flag to publish all exposedports and map them to high-order ports.

3a8082e126