github.com/amanya/packer@v0.12.1-0.20161117214323-902ac5ab2eb6/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 exports 5 the container for reuse or commits the image. 6 layout: docs 7 page_title: Docker Builder 8 ... 9 10 # Docker Builder 11 12 Type: `docker` 13 14 The `docker` Packer builder builds [Docker](https://www.docker.io) images using 15 Docker. The builder starts a Docker container, runs provisioners within this 16 container, then exports the container for reuse or commits the image. 17 18 Packer builds Docker containers *without* the use of 19 [Dockerfiles](https://docs.docker.com/reference/builder/). By not using 20 Dockerfiles, Packer is able to provision containers with portable scripts or 21 configuration management systems that are not tied to Docker in any way. It also 22 has a simpler mental model: you provision containers much the same way you 23 provision a normal virtualized or dedicated server. For more information, read 24 the section on [Dockerfiles](#toc_8). 25 26 The Docker builder must run on a machine that has Docker installed. Therefore 27 the builder only works on machines that support Docker (modern Linux machines). 28 If you want to use Packer to build Docker containers on another platform, use 29 [Vagrant](https://www.vagrantup.com) to start a Linux environment, then run 30 Packer within that environment. 31 32 ## Basic Example: Export 33 34 Below is a fully functioning example. It doesn't do anything useful, since no 35 provisioners are defined, but it will effectively repackage an image. 36 37 ``` {.javascript} 38 { 39 "type": "docker", 40 "image": "ubuntu", 41 "export_path": "image.tar" 42 } 43 ``` 44 45 ## Basic Example: Commit 46 47 Below is another example, the same as above but instead of exporting the running 48 container, this one commits the container to an image. The image can then be 49 more easily tagged, pushed, etc. 50 51 ``` {.javascript} 52 { 53 "type": "docker", 54 "image": "ubuntu", 55 "commit": true 56 } 57 ``` 58 59 ## Configuration Reference 60 61 Configuration options are organized below into two categories: required and 62 optional. Within each category, the available options are alphabetized and 63 described. 64 65 In addition to the options listed here, a 66 [communicator](/docs/templates/communicator.html) can be configured for this 67 builder. 68 69 ### Required: 70 71 You must specify (only) one of `commit`, `discard`, or `export_path`. 72 73 - `commit` (boolean) - If true, the container will be committed to an image 74 rather than exported. 75 76 - `discard` (boolean) - Throw away the container when the build is complete. 77 This is useful for the [artifice 78 post-processor](https://www.packer.io/docs/post-processors/artifice.html). 79 80 - `export_path` (string) - The path where the final container will be exported 81 as a tar file. 82 83 - `image` (string) - The base image for the Docker container that will 84 be started. This image will be pulled from the Docker registry if it doesn't 85 already exist. 86 87 ### Optional: 88 89 - `aws_access_key` (string) - The AWS access key used to communicate with AWS. 90 [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 91 92 - `aws_secret_key` (string) - The AWS secret key used to communicate with AWS. 93 [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 94 95 - `aws_token` (string) - The AWS access token to use. This is different from the 96 access key and secret key. If you're not sure what this is, then you 97 probably don't need it. This will also be read from the `AWS_SESSION_TOKEN` 98 environmental variable. 99 100 - `ecr_login` (boolean) - Defaults to false. If true, the builder will login in 101 order to pull the image from 102 [Amazon EC2 Container Registry (ECR)](https://aws.amazon.com/ecr/). 103 The builder only logs in for the duration of the pull. If true 104 `login_server` is required and `login`, `login_username`, and 105 `login_password` will be ignored. 106 107 - `login` (boolean) - Defaults to false. If true, the builder will login in 108 order to pull the image. The builder only logs in for the duration of 109 the pull. It always logs out afterwards. For log into ECR see `ecr_login`. 110 111 - `login_email` (string) - The email to use to authenticate to login. 112 113 - `login_username` (string) - The username to use to authenticate to login. 114 115 - `login_password` (string) - The password to use to authenticate to login. 116 117 - `login_server` (string) - The server address to login to. 118 119 - `privileged` (boolean) - If true, run the docker container with the 120 `--privileged` flag. This defaults to false if not set. 121 122 - `pull` (boolean) - If true, the configured image will be pulled using 123 `docker pull` prior to use. Otherwise, it is assumed the image already 124 exists and can be used. This defaults to true if not set. 125 126 - `run_command` (array of strings) - An array of arguments to pass to 127 `docker run` in order to run the container. By default this is set to 128 `["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. As you can see, you have a 129 couple template variables to customize, as well. 130 131 - `volumes` (map of strings to strings) - A mapping of additional volumes to 132 mount into this container. The key of the object is the host path, the value 133 is the container path. 134 135 ## Using the Artifact: Export 136 137 Once the tar artifact has been generated, you will likely want to import, tag, 138 and push it to a container repository. Packer can do this for you automatically 139 with the [docker-import](/docs/post-processors/docker-import.html) and 140 [docker-push](/docs/post-processors/docker-push.html) post-processors. 141 142 **Note:** This section is covering how to use an artifact that has been 143 *exported*. More specifically, if you set `export_path` in your configuration. 144 If you set `commit`, see the next section. 145 146 The example below shows a full configuration that would import and push the 147 created image. This is accomplished using a sequence definition (a collection of 148 post-processors that are treated as as single pipeline, see 149 [Post-Processors](/docs/templates/post-processors.html) for more information): 150 151 ``` {.javascript} 152 { 153 "post-processors": [ 154 [ 155 { 156 "type": "docker-import", 157 "repository": "mitchellh/packer", 158 "tag": "0.7" 159 }, 160 "docker-push" 161 ] 162 ] 163 } 164 ``` 165 166 In the above example, the result of each builder is passed through the defined 167 sequence of post-processors starting first with the `docker-import` 168 post-processor which will import the artifact as a docker image. The resulting 169 docker image is then passed on to the `docker-push` post-processor which handles 170 pushing the image to a container repository. 171 172 If you want to do this manually, however, perhaps from a script, you can import 173 the image using the process below: 174 175 ``` {.text} 176 $ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar 177 ``` 178 179 You can then add additional tags and push the image as usual with `docker tag` 180 and `docker push`, respectively. 181 182 ## Using the Artifact: Committed 183 184 If you committed your container to an image, you probably want to tag, save, 185 push, etc. Packer can do this automatically for you. An example is shown below 186 which tags and pushes an image. This is accomplished using a sequence definition 187 (a collection of post-processors that are treated as as single pipeline, see 188 [Post-Processors](/docs/templates/post-processors.html) for more information): 189 190 ``` {.javascript} 191 { 192 "post-processors": [ 193 [ 194 { 195 "type": "docker-tag", 196 "repository": "mitchellh/packer", 197 "tag": "0.7" 198 }, 199 "docker-push" 200 ] 201 ] 202 } 203 ``` 204 205 In the above example, the result of each builder is passed through the defined 206 sequence of post-processors starting first with the `docker-tag` post-processor 207 which tags the committed image with the supplied repository and tag information. 208 Once tagged, the resulting artifact is then passed on to the `docker-push` 209 post-processor which handles pushing the image to a container repository. 210 211 Going a step further, if you wanted to tag and push an image to multiple 212 container repositories, this could be accomplished by defining two, 213 nearly-identical sequence definitions, as demonstrated by the example below: 214 215 ``` {.javascript} 216 { 217 "post-processors": [ 218 [ 219 { 220 "type": "docker-tag", 221 "repository": "mitchellh/packer", 222 "tag": "0.7" 223 }, 224 "docker-push" 225 ], 226 [ 227 { 228 "type": "docker-tag", 229 "repository": "hashicorp/packer", 230 "tag": "0.7" 231 }, 232 "docker-push" 233 ] 234 ] 235 } 236 ``` 237 238 <span id="amazon-ec2-container-registry"></span> 239 240 ## Amazon EC2 Container Registry 241 242 Packer can tag and push images for use in 243 [Amazon EC2 Container Registry](https://aws.amazon.com/ecr/). The post 244 processors work as described above and example configuration properties are 245 shown below: 246 247 ``` {.javascript} 248 { 249 "post-processors": [ 250 [ 251 { 252 "type": "docker-tag", 253 "repository": "12345.dkr.ecr.us-east-1.amazonaws.com/packer", 254 "tag": "0.7" 255 }, 256 { 257 "type": "docker-push", 258 "ecr_login": true, 259 "aws_access_key": "YOUR KEY HERE", 260 "aws_secret_key": "YOUR SECRET KEY HERE", 261 "login_server": "https://12345.dkr.ecr.us-east-1.amazonaws.com/" 262 } 263 ] 264 ] 265 } 266 ``` 267 268 [Learn how to set Amazon AWS credentials.](/docs/builders/amazon.html#specifying-amazon-credentials) 269 270 ## Dockerfiles 271 272 This builder allows you to build Docker images *without* Dockerfiles. 273 274 With this builder, you can repeatably create Docker images without the use of a 275 Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. 276 Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, 277 etc. to provision your Docker container just like you would a regular 278 virtualized or dedicated machine. 279 280 While Docker has many features, Packer views Docker simply as an container 281 runner. To that end, Packer is able to repeatably build these containers 282 using portable provisioning scripts. 283 284 Dockerfiles have some additional features that Packer doesn't support which are 285 able to be worked around. Many of these features will be automated by Packer in 286 the future: 287 288 - Dockerfiles will snapshot the container at each step, allowing you to go 289 back to any step in the history of building. Packer doesn't do this yet, but 290 inter-step snapshotting is on the way. 291 292 - Dockerfiles can contain information such as exposed ports, shared volumes, 293 and other metadata. Packer builds a raw Docker container image that has none 294 of this metadata. You can pass in much of this metadata at runtime with 295 `docker run`.