github.com/lmars/docker@v1.6.0-rc2/docs/man/Dockerfile.5.md (about) 1 % DOCKERFILE(5) Docker User Manuals 2 % Zac Dover 3 % May 2014 4 # NAME 5 6 Dockerfile - automate the steps of creating a Docker image 7 8 # INTRODUCTION 9 10 The **Dockerfile** is a configuration file that automates the steps of creating 11 a Docker image. It is similar to a Makefile. Docker reads instructions from the 12 **Dockerfile** to automate the steps otherwise performed manually to create an 13 image. To build an image, create a file called **Dockerfile**. 14 15 The **Dockerfile** describes the steps taken to assemble the image. When the 16 **Dockerfile** has been created, call the `docker build` command, using the 17 path of directory that contains **Dockerfile** as the argument. 18 19 # SYNOPSIS 20 21 INSTRUCTION arguments 22 23 For example: 24 25 FROM image 26 27 # DESCRIPTION 28 29 A Dockerfile is a file that automates the steps of creating a Docker image. 30 A Dockerfile is similar to a Makefile. 31 32 # USAGE 33 34 sudo docker build . 35 36 -- Runs the steps and commits them, building a final image. 37 The path to the source repository defines where to find the context of the 38 build. The build is run by the Docker daemon, not the CLI. The whole 39 context must be transferred to the daemon. The Docker CLI reports 40 `"Sending build context to Docker daemon"` when the context is sent to the 41 daemon. 42 43 ``` 44 sudo docker build -t repository/tag . 45 ``` 46 47 -- specifies a repository and tag at which to save the new image if the build 48 succeeds. The Docker daemon runs the steps one-by-one, committing the result 49 to a new image if necessary, before finally outputting the ID of the new 50 image. The Docker daemon automatically cleans up the context it is given. 51 52 Docker re-uses intermediate images whenever possible. This significantly 53 accelerates the *docker build* process. 54 55 # FORMAT 56 57 `FROM image` 58 59 `FROM image:tag` 60 61 -- The **FROM** instruction sets the base image for subsequent instructions. A 62 valid Dockerfile must have **FROM** as its first instruction. The image can be any 63 valid image. It is easy to start by pulling an image from the public 64 repositories. 65 66 -- **FROM** must be the first non-comment instruction in Dockerfile. 67 68 -- **FROM** may appear multiple times within a single Dockerfile in order to create 69 multiple images. Make a note of the last image ID output by the commit before 70 each new **FROM** command. 71 72 -- If no tag is given to the **FROM** instruction, latest is assumed. If the 73 used tag does not exist, an error is returned. 74 75 **MAINTAINER** 76 -- **MAINTAINER** sets the Author field for the generated images. 77 78 **RUN** 79 -- **RUN** has two forms: 80 81 ``` 82 # the command is run in a shell - /bin/sh -c 83 RUN <command> 84 85 # Executable form 86 RUN ["executable", "param1", "param2"] 87 ``` 88 89 90 -- The **RUN** instruction executes any commands in a new layer on top of the current 91 image and commits the results. The committed image is used for the next step in 92 Dockerfile. 93 94 -- Layering **RUN** instructions and generating commits conforms to the core 95 concepts of Docker where commits are cheap and containers can be created from 96 any point in the history of an image. This is similar to source control. The 97 exec form makes it possible to avoid shell string munging. The exec form makes 98 it possible to **RUN** commands using a base image that does not contain `/bin/sh`. 99 100 Note that the exec form is parsed as a JSON array, which means that you must 101 use double-quotes (") around words not single-quotes ('). 102 103 **CMD** 104 -- **CMD** has three forms: 105 106 ``` 107 # Executable form 108 CMD ["executable", "param1", "param2"]` 109 110 # Provide default arguments to ENTRYPOINT 111 CMD ["param1", "param2"]` 112 113 # the command is run in a shell - /bin/sh -c 114 CMD command param1 param2 115 ``` 116 117 -- There can be only one **CMD** in a Dockerfile. If more than one **CMD** is listed, only 118 the last **CMD** takes effect. 119 The main purpose of a **CMD** is to provide defaults for an executing container. 120 These defaults may include an executable, or they can omit the executable. If 121 they omit the executable, an **ENTRYPOINT** must be specified. 122 When used in the shell or exec formats, the **CMD** instruction sets the command to 123 be executed when running the image. 124 If you use the shell form of the **CMD**, the `<command>` executes in `/bin/sh -c`: 125 126 Note that the exec form is parsed as a JSON array, which means that you must 127 use double-quotes (") around words not single-quotes ('). 128 129 ``` 130 FROM ubuntu 131 CMD echo "This is a test." | wc - 132 ``` 133 134 -- If you run **command** without a shell, then you must express the command as a 135 JSON array and give the full path to the executable. This array form is the 136 preferred form of **CMD**. All additional parameters must be individually expressed 137 as strings in the array: 138 139 ``` 140 FROM ubuntu 141 CMD ["/usr/bin/wc","--help"] 142 ``` 143 144 -- To make the container run the same executable every time, use **ENTRYPOINT** in 145 combination with **CMD**. 146 If the user specifies arguments to `docker run`, the specified commands 147 override the default in **CMD**. 148 Do not confuse **RUN** with **CMD**. **RUN** runs a command and commits the result. 149 **CMD** executes nothing at build time, but specifies the intended command for 150 the image. 151 152 **LABEL** 153 -- `LABEL <key>[=<value>] [<key>[=<value>] ...]` 154 The **LABEL** instruction adds metadata to an image. A **LABEL** is a 155 key-value pair. To include spaces within a **LABEL** value, use quotes and 156 backslashes as you would in command-line parsing. 157 158 ``` 159 LABEL "com.example.vendor"="ACME Incorporated" 160 ``` 161 162 An image can have more than one label. To specify multiple labels, separate 163 each key-value pair by a space. 164 165 Labels are additive including `LABEL`s in `FROM` images. As the system 166 encounters and then applies a new label, new `key`s override any previous 167 labels with identical keys. 168 169 To display an image's labels, use the `docker inspect` command. 170 171 **EXPOSE** 172 -- `EXPOSE <port> [<port>...]` 173 The **EXPOSE** instruction informs Docker that the container listens on the 174 specified network ports at runtime. Docker uses this information to 175 interconnect containers using links, and to set up port redirection on the host 176 system. 177 178 **ENV** 179 -- `ENV <key> <value>` 180 The **ENV** instruction sets the environment variable <key> to 181 the value `<value>`. This value is passed to all future 182 RUN, **ENTRYPOINT**, and **CMD** instructions. This is 183 functionally equivalent to prefixing the command with `<key>=<value>`. The 184 environment variables that are set with **ENV** persist when a container is run 185 from the resulting image. Use `docker inspect` to inspect these values, and 186 change them using `docker run --env <key>=<value>`. 187 188 Note that setting "`ENV DEBIAN_FRONTEND noninteractive`" may cause 189 unintended consequences, because it will persist when the container is run 190 interactively, as with the following command: `docker run -t -i image bash` 191 192 **ADD** 193 -- **ADD** has two forms: 194 195 ``` 196 ADD <src> <dest> 197 198 # Required for paths with whitespace 199 ADD ["<src>", "<dest>"] 200 ``` 201 202 The **ADD** instruction copies new files, directories 203 or remote file URLs to the filesystem of the container at path `<dest>`. 204 Multiple `<src>` resources may be specified but if they are files or directories 205 then they must be relative to the source directory that is being built 206 (the context of the build). The `<dest>` is the absolute path, or path relative 207 to **WORKDIR**, into which the source is copied inside the target container. 208 All new files and directories are created with mode 0755 and with the uid 209 and gid of **0**. 210 211 **COPY** 212 -- **COPY** has two forms: 213 214 ``` 215 COPY <src> <dest> 216 217 # Required for paths with whitespace 218 COPY ["<src>", "<dest>"] 219 ``` 220 221 The **COPY** instruction copies new files from `<src>` and 222 adds them to the filesystem of the container at path <dest>. The `<src>` must be 223 the path to a file or directory relative to the source directory that is 224 being built (the context of the build) or a remote file URL. The `<dest>` is an 225 absolute path, or a path relative to **WORKDIR**, into which the source will 226 be copied inside the target container. All new files and directories are 227 created with mode **0755** and with the uid and gid of **0**. 228 229 **ENTRYPOINT** 230 -- **ENTRYPOINT** has two forms: 231 232 ``` 233 # executable form 234 ENTRYPOINT ["executable", "param1", "param2"]` 235 236 # run command in a shell - /bin/sh -c 237 ENTRYPOINT command param1 param2 238 ``` 239 240 -- An **ENTRYPOINT** helps you configure a 241 container that can be run as an executable. When you specify an **ENTRYPOINT**, 242 the whole container runs as if it was only that executable. The **ENTRYPOINT** 243 instruction adds an entry command that is not overwritten when arguments are 244 passed to docker run. This is different from the behavior of CMD. This allows 245 arguments to be passed to the entrypoint, for instance `docker run <image> -d` 246 passes the -d argument to the **ENTRYPOINT**. Specify parameters either in the 247 **ENTRYPOINT** JSON array (as in the preferred exec form above), or by using a **CMD** 248 statement. Parameters in the **ENTRYPOINT** are not overwritten by the docker run 249 arguments. Parameters specifies via **CMD** are overwritten by docker run 250 arguments. Specify a plain string for the **ENTRYPOINT**, and it will execute in 251 `/bin/sh -c`, like a **CMD** instruction: 252 253 ``` 254 FROM ubuntu 255 ENTRYPOINT wc -l - 256 ``` 257 258 This means that the Dockerfile's image always takes stdin as input (that's 259 what "-" means), and prints the number of lines (that's what "-l" means). To 260 make this optional but default, use a **CMD**: 261 262 ``` 263 FROM ubuntu 264 CMD ["-l", "-"] 265 ENTRYPOINT ["/usr/bin/wc"] 266 ``` 267 268 **VOLUME** 269 -- `VOLUME ["/data"]` 270 The **VOLUME** instruction creates a mount point with the specified name and marks 271 it as holding externally-mounted volumes from the native host or from other 272 containers. 273 274 **USER** 275 -- `USER daemon` 276 The **USER** instruction sets the username or UID that is used when running the 277 image. 278 279 **WRKDIR** 280 -- `WORKDIR /path/to/workdir` 281 The **WORKDIR** instruction sets the working directory for the **RUN**, **CMD**, 282 **ENTRYPOINT**, **COPY** and **ADD** Dockerfile commands that follow it. It can 283 be used multiple times in a single Dockerfile. Relative paths are defined 284 relative to the path of the previous **WORKDIR** instruction. For example: 285 286 ``` 287 WORKDIR /a 288 WORKDIR b 289 WORKDIR c 290 RUN pwd 291 ``` 292 293 In the above example, the output of the **pwd** command is **a/b/c**. 294 295 **ONBUILD** 296 -- `ONBUILD [INSTRUCTION]` 297 The **ONBUILD** instruction adds a trigger instruction to an image. The 298 trigger is executed at a later time, when the image is used as the base for 299 another build. Docker executes the trigger in the context of the downstream 300 build, as if the trigger existed immediately after the **FROM** instruction in 301 the downstream Dockerfile. 302 303 You can register any build instruction as a trigger. A trigger is useful if 304 you are defining an image to use as a base for building other images. For 305 example, if you are defining an application build environment or a daemon that 306 is customized with a user-specific configuration. 307 308 Consider an image intended as a reusable python application builder. It must 309 add application source code to a particular directory, and might need a build 310 script called after that. You can't just call **ADD** and **RUN** now, because 311 you don't yet have access to the application source code, and it is different 312 for each application build. 313 314 -- Providing application developers with a boilerplate Dockerfile to copy-paste 315 into their application is inefficient, error-prone, and 316 difficult to update because it mixes with application-specific code. 317 The solution is to use **ONBUILD** to register instructions in advance, to 318 run later, during the next build stage. 319 320 # HISTORY 321 *May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation. 322 *Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability