github.com/raghuse92/packer@v1.3.2/website/source/docs/builders/docker.html.md (about) 1 --- 2 description: | 3 The docker Packer builder builds Docker images using Docker. The builder 4 starts a Docker container, runs provisioners within this container, then 5 exports the container for reuse or commits the image. 6 layout: docs 7 page_title: 'Docker - Builders' 8 sidebar_current: 'docs-builders-docker' 9 --- 10 11 # Docker Builder 12 13 Type: `docker` 14 15 The `docker` Packer builder builds [Docker](https://www.docker.io) images using 16 Docker. The builder starts a Docker container, runs provisioners within this 17 container, then exports the container for reuse or commits the image. 18 19 Packer builds Docker containers *without* the use of 20 [Dockerfiles](https://docs.docker.com/engine/reference/builder/). By not using 21 `Dockerfiles`, Packer is able to provision containers with portable scripts or 22 configuration management systems that are not tied to Docker in any way. It also 23 has a simple mental model: you provision containers much the same way you 24 provision a normal virtualized or dedicated server. For more information, read 25 the section on [Dockerfiles](#dockerfiles). 26 27 The Docker builder must run on a machine that has Docker Engine installed. 28 Therefore the builder only works on machines that support Docker and _does not 29 support running on a Docker remote host_. You can learn about what 30 [platforms Docker supports and how to install onto them](https://docs.docker.com/engine/installation/) 31 in the Docker documentation. 32 33 34 Please note: Packer does not yet have support for Windows containers. 35 36 37 ## Basic Example: Export 38 39 Below is a fully functioning example. It doesn't do anything useful, since no 40 provisioners are defined, but it will effectively repackage an image. 41 42 ``` json 43 { 44 "type": "docker", 45 "image": "ubuntu", 46 "export_path": "image.tar" 47 } 48 ``` 49 50 ## Basic Example: Commit 51 52 Below is another example, the same as above but instead of exporting the running 53 container, this one commits the container to an image. The image can then be 54 more easily tagged, pushed, etc. 55 56 ``` json 57 { 58 "type": "docker", 59 "image": "ubuntu", 60 "commit": true 61 } 62 ``` 63 64 ## Basic Example: Changes to Metadata 65 66 Below is an example using the changes argument of the builder. This feature 67 allows the source images metadata to be changed when committed back into the 68 Docker environment. It is derived from the `docker commit --change` command 69 line [option to 70 Docker](https://docs.docker.com/engine/reference/commandline/commit/). 71 72 Example uses of all of the options, assuming one is building an NGINX image 73 from ubuntu as an simple example: 74 75 ``` json 76 { 77 "type": "docker", 78 "image": "ubuntu", 79 "commit": true, 80 "changes": [ 81 "USER www-data", 82 "WORKDIR /var/www", 83 "ENV HOSTNAME www.example.com", 84 "VOLUME /test1 /test2", 85 "EXPOSE 80 443", 86 "LABEL version=1.0", 87 "ONBUILD RUN date", 88 "CMD [\"nginx\", \"-g\", \"daemon off;\"]", 89 "ENTRYPOINT /var/www/start.sh" 90 ] 91 } 92 ``` 93 94 Allowed metadata fields that can be changed are: 95 96 - CMD 97 - String, supports both array (escaped) and string form 98 - EX: `"CMD [\"nginx\", \"-g\", \"daemon off;\"]"` 99 - EX: `"CMD nginx -g daemon off;"` 100 - ENTRYPOINT 101 - String 102 - EX: `"ENTRYPOINT /var/www/start.sh"` 103 - ENV 104 - String, note there is no equal sign: 105 - EX: `"ENV HOSTNAME www.example.com"` not `"ENV HOSTNAME=www.example.com"` 106 - EXPOSE 107 - String, space separated ports 108 - EX: `"EXPOSE 80 443"` 109 - LABEL 110 - String, space separated key=value pairs 111 - EX: `"LABEL version=1.0"` 112 - ONBUILD 113 - String 114 - EX: `"ONBUILD RUN date"` 115 - MAINTAINER 116 - String, deprecated in Docker version 1.13.0 117 - EX: `"MAINTAINER NAME"` 118 - USER 119 - String 120 - EX: `"USER USERNAME"` 121 - VOLUME 122 - String 123 - EX: `"VOLUME FROM TO"` 124 - WORKDIR 125 - String 126 - EX: `"WORKDIR PATH"` 127 128 ## Configuration Reference 129 130 Configuration options are organized below into two categories: required and 131 optional. Within each category, the available options are alphabetized and 132 described. 133 134 The Docker builder uses a special Docker communicator _and will not use_ the 135 standard [communicators](/docs/templates/communicator.html). 136 137 ### Required: 138 139 You must specify (only) one of `commit`, `discard`, or `export_path`. 140 141 - `commit` (boolean) - If true, the container will be committed to an image 142 rather than exported. 143 144 - `discard` (boolean) - Throw away the container when the build is complete. 145 This is useful for the [artifice 146 post-processor](https://www.packer.io/docs/post-processors/artifice.html). 147 148 - `export_path` (string) - The path where the final container will be exported 149 as a tar file. 150 151 - `image` (string) - The base image for the Docker container that will 152 be started. This image will be pulled from the Docker registry if it doesn't 153 already exist. 154 155 ### Optional: 156 157 - `author` (string) - Set the author (e-mail) of a commit. 158 159 - `aws_access_key` (string) - The AWS access key used to communicate with AWS. 160 [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 161 162 - `aws_secret_key` (string) - The AWS secret key used to communicate with AWS. 163 [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 164 165 - `aws_token` (string) - The AWS access token to use. This is different from the 166 access key and secret key. If you're not sure what this is, then you 167 probably don't need it. This will also be read from the `AWS_SESSION_TOKEN` 168 environmental variable. 169 170 - `aws_profile` (string) - The AWS shared credentials profile used to communicate with AWS. 171 [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 172 173 - `changes` (array of strings) - Dockerfile instructions to add to the commit. 174 Example of instructions are `CMD`, `ENTRYPOINT`, `ENV`, and `EXPOSE`. Example: 175 `[ "USER ubuntu", "WORKDIR /app", "EXPOSE 8080" ]` 176 177 - `ecr_login` (boolean) - Defaults to false. If true, the builder will login in 178 order to pull the image from 179 [Amazon EC2 Container Registry (ECR)](https://aws.amazon.com/ecr/). 180 The builder only logs in for the duration of the pull. If true 181 `login_server` is required and `login`, `login_username`, and 182 `login_password` will be ignored. For more information see the 183 [section on ECR](#amazon-ec2-container-registry). 184 185 * `exec_user` (string) - Username or UID (format: <name|uid>[:<group|gid>]) 186 to run remote commands with. You may need this if you get permission errors 187 trying to run the `shell` or other provisioners. 188 189 - `login` (boolean) - Defaults to false. If true, the builder will login in 190 order to pull the image. The builder only logs in for the duration of 191 the pull. It always logs out afterwards. For log into ECR see `ecr_login`. 192 193 - `login_username` (string) - The username to use to authenticate to login. 194 195 - `login_password` (string) - The password to use to authenticate to login. 196 197 - `login_server` (string) - The server address to login to. 198 199 - `message` (string) - Set a message for the commit. 200 201 - `privileged` (boolean) - If true, run the docker container with the 202 `--privileged` flag. This defaults to false if not set. 203 204 - `pull` (boolean) - If true, the configured image will be pulled using 205 `docker pull` prior to use. Otherwise, it is assumed the image already 206 exists and can be used. This defaults to true if not set. 207 208 - `run_command` (array of strings) - An array of arguments to pass to 209 `docker run` in order to run the container. By default this is set to 210 `["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. As you can see, you have a 211 couple template variables to customize, as well. 212 213 - `volumes` (map of strings to strings) - A mapping of additional volumes to 214 mount into this container. The key of the object is the host path, the value 215 is the container path. 216 217 - `container_dir` (string) - The directory inside container to mount 218 temp directory from host server for work [file provisioner](/docs/provisioners/file.html). 219 By default this is set to `/packer-files`. 220 221 - `fix_upload_owner` (boolean) - If true, files uploaded to the container will 222 be owned by the user the container is running as. If false, the owner will depend 223 on the version of docker installed in the system. Defaults to true. 224 225 ## Using the Artifact: Export 226 227 Once the tar artifact has been generated, you will likely want to import, tag, 228 and push it to a container repository. Packer can do this for you automatically 229 with the [docker-import](/docs/post-processors/docker-import.html) and 230 [docker-push](/docs/post-processors/docker-push.html) post-processors. 231 232 **Note:** This section is covering how to use an artifact that has been 233 *exported*. More specifically, if you set `export_path` in your configuration. 234 If you set `commit`, see the next section. 235 236 The example below shows a full configuration that would import and push the 237 created image. This is accomplished using a sequence definition (a collection of 238 post-processors that are treated as as single pipeline, see 239 [Post-Processors](/docs/templates/post-processors.html) for more information): 240 241 ``` json 242 { 243 "post-processors": [ 244 [ 245 { 246 "type": "docker-import", 247 "repository": "hashicorp/packer", 248 "tag": "0.7" 249 }, 250 "docker-push" 251 ] 252 ] 253 } 254 ``` 255 256 In the above example, the result of each builder is passed through the defined 257 sequence of post-processors starting first with the `docker-import` 258 post-processor which will import the artifact as a docker image. The resulting 259 docker image is then passed on to the `docker-push` post-processor which handles 260 pushing the image to a container repository. 261 262 If you want to do this manually, however, perhaps from a script, you can import 263 the image using the process below: 264 265 ``` shell 266 $ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar 267 ``` 268 269 You can then add additional tags and push the image as usual with `docker tag` 270 and `docker push`, respectively. 271 272 ## Using the Artifact: Committed 273 274 If you committed your container to an image, you probably want to tag, save, 275 push, etc. Packer can do this automatically for you. An example is shown below 276 which tags and pushes an image. This is accomplished using a sequence definition 277 (a collection of post-processors that are treated as as single pipeline, see 278 [Post-Processors](/docs/templates/post-processors.html) for more information): 279 280 ``` json 281 { 282 "post-processors": [ 283 [ 284 { 285 "type": "docker-tag", 286 "repository": "hashicorp/packer", 287 "tag": "0.7" 288 }, 289 "docker-push" 290 ] 291 ] 292 } 293 ``` 294 295 In the above example, the result of each builder is passed through the defined 296 sequence of post-processors starting first with the `docker-tag` post-processor 297 which tags the committed image with the supplied repository and tag information. 298 Once tagged, the resulting artifact is then passed on to the `docker-push` 299 post-processor which handles pushing the image to a container repository. 300 301 Going a step further, if you wanted to tag and push an image to multiple 302 container repositories, this could be accomplished by defining two, 303 nearly-identical sequence definitions, as demonstrated by the example below: 304 305 ``` json 306 { 307 "post-processors": [ 308 [ 309 { 310 "type": "docker-tag", 311 "repository": "hashicorp/packer1", 312 "tag": "0.7" 313 }, 314 "docker-push" 315 ], 316 [ 317 { 318 "type": "docker-tag", 319 "repository": "hashicorp/packer2", 320 "tag": "0.7" 321 }, 322 "docker-push" 323 ] 324 ] 325 } 326 ``` 327 328 <span id="amazon-ec2-container-registry"></span> 329 330 ## Amazon EC2 Container Registry 331 332 Packer can tag and push images for use in 333 [Amazon EC2 Container Registry](https://aws.amazon.com/ecr/). The post 334 processors work as described above and example configuration properties are 335 shown below: 336 337 ``` json 338 { 339 "post-processors": [ 340 [ 341 { 342 "type": "docker-tag", 343 "repository": "12345.dkr.ecr.us-east-1.amazonaws.com/packer", 344 "tag": "0.7" 345 }, 346 { 347 "type": "docker-push", 348 "ecr_login": true, 349 "aws_access_key": "YOUR KEY HERE", 350 "aws_secret_key": "YOUR SECRET KEY HERE", 351 "login_server": "https://12345.dkr.ecr.us-east-1.amazonaws.com/" 352 } 353 ] 354 ] 355 } 356 ``` 357 358 [Learn how to set Amazon AWS credentials.](/docs/builders/amazon.html#specifying-amazon-credentials) 359 360 ## Dockerfiles 361 362 This builder allows you to build Docker images *without* Dockerfiles. 363 364 With this builder, you can repeatedly create Docker images without the use of a 365 Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. 366 Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, 367 etc. to provision your Docker container just like you would a regular 368 virtualized or dedicated machine. 369 370 While Docker has many features, Packer views Docker simply as an container 371 runner. To that end, Packer is able to repeatedly build these containers 372 using portable provisioning scripts. 373 374 ## Overriding the host directory 375 376 By default, Packer creates a temporary folder under your home directory, and 377 uses that to stage files for uploading into the container. If you would like to 378 change the path to this temporary folder, you can set the `PACKER_TMP_DIR` 379 environment variable. This can be useful, for example, if you have your home 380 directory permissions set up to disallow access from the docker daemon.