From 48badd2a2e3a6712baa6fce1e97e87e1feb3dc38 Mon Sep 17 00:00:00 2001 From: Sally O'Malley Date: Thu, 3 Sep 2015 05:49:19 -0400 Subject: [PATCH] man Dockerfile ADD/COPY/FROM clarify Signed-off-by: Sally O'Malley --- man/Dockerfile.5.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/man/Dockerfile.5.md b/man/Dockerfile.5.md index b4ef771a45..0b188ac330 100644 --- a/man/Dockerfile.5.md +++ b/man/Dockerfile.5.md @@ -58,6 +58,8 @@ A Dockerfile is similar to a Makefile. `FROM image:tag` + `FROM image@digest` + -- The **FROM** instruction sets the base image for subsequent instructions. A valid Dockerfile must have **FROM** as its first instruction. The image can be any valid image. It is easy to start by pulling an image from the public @@ -72,8 +74,12 @@ A Dockerfile is similar to a Makefile. -- If no tag is given to the **FROM** instruction, Docker applies the `latest` tag. If the used tag does not exist, an error is returned. + -- If no digest is given to the **FROM** instruction, Docker applies the + `latest` tag. If the used tag does not exist, an error is returned. + **MAINTAINER** -- **MAINTAINER** sets the Author field for the generated images. + Useful for providing users with an email or url for support. **RUN** -- **RUN** has two forms: @@ -114,7 +120,7 @@ A Dockerfile is similar to a Makefile. CMD command param1 param2 ``` - -- There can be only one **CMD** in a Dockerfile. If more than one **CMD** is listed, only + -- There should be only one **CMD** in a Dockerfile. If more than one **CMD** is listed, only the last **CMD** takes effect. The main purpose of a **CMD** is to provide defaults for an executing container. These defaults may include an executable, or they can omit the executable. If @@ -150,13 +156,20 @@ A Dockerfile is similar to a Makefile. the image. **LABEL** - -- `LABEL [=] [[=] ...]` + -- `LABEL [=] [[=] ...]`or + ``` + LABEL [ ] + LABEL [ ] + ... + ``` The **LABEL** instruction adds metadata to an image. A **LABEL** is a key-value pair. To include spaces within a **LABEL** value, use quotes and backslashes as you would in command-line parsing. ``` - LABEL "com.example.vendor"="ACME Incorporated" + LABEL com.example.vendor="ACME Incorporated" + or + LABEL com.example.vendor "ACME Incorporated" ``` An image can have more than one label. To specify multiple labels, separate @@ -179,7 +192,7 @@ A Dockerfile is similar to a Makefile. -- `ENV ` The **ENV** instruction sets the environment variable to the value ``. This value is passed to all future - RUN, **ENTRYPOINT**, and **CMD** instructions. This is + **RUN**, **ENTRYPOINT**, and **CMD** instructions. This is functionally equivalent to prefixing the command with `=`. The environment variables that are set with **ENV** persist when a container is run from the resulting image. Use `docker inspect` to inspect these values, and @@ -205,8 +218,11 @@ A Dockerfile is similar to a Makefile. then they must be relative to the source directory that is being built (the context of the build). The `` is the absolute path, or path relative to **WORKDIR**, into which the source is copied inside the target container. - All new files and directories are created with mode 0755 and with the uid - and gid of **0**. + If the `` argument is a local file in a recognized compression format + (tar, gzip, bzip2, etc) then it is unpacked at the specified `` in the + container's filesystem. Note that only local compressed files will be unpacked, + i.e., the URL download and archive unpacking features cannot be used together. + All new directories are created with mode 0755 and with the uid and gid of **0**. **COPY** -- **COPY** has two forms: @@ -223,8 +239,10 @@ A Dockerfile is similar to a Makefile. the path to a file or directory relative to the source directory that is being built (the context of the build) or a remote file URL. The `` is an absolute path, or a path relative to **WORKDIR**, into which the source will - be copied inside the target container. All new files and directories are - created with mode **0755** and with the uid and gid of **0**. + be copied inside the target container. If you **COPY** an archive file it will + land in the container exactly as it appears in the build context without any + attempt to unpack it. All new files and directories are created with mode **0755** + and with the uid and gid of **0**. **ENTRYPOINT** -- **ENTRYPOINT** has two forms: @@ -241,7 +259,7 @@ A Dockerfile is similar to a Makefile. container that can be run as an executable. When you specify an **ENTRYPOINT**, the whole container runs as if it was only that executable. The **ENTRYPOINT** instruction adds an entry command that is not overwritten when arguments are - passed to docker run. This is different from the behavior of CMD. This allows + passed to docker run. This is different from the behavior of **CMD**. This allows arguments to be passed to the entrypoint, for instance `docker run -d` passes the -d argument to the **ENTRYPOINT**. Specify parameters either in the **ENTRYPOINT** JSON array (as in the preferred exec form above), or by using a **CMD** @@ -327,3 +345,4 @@ A Dockerfile is similar to a Makefile. # HISTORY *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation. *Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability +*Sept 2015, updated by Sally O'Malley (somalley@redhat.com)