github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/docker.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Docker Builder" 4 description: |- 5 The `docker` Packer builder builds Docker images using Docker. The builder starts a Docker container, runs provisioners within this container, then exports the container for reuse or commits the image. 6 --- 7 8 # Docker Builder 9 10 Type: `docker` 11 12 The `docker` Packer builder builds [Docker](http://www.docker.io) images using 13 Docker. The builder starts a Docker container, runs provisioners within 14 this container, then exports the container for reuse or commits the image. 15 16 Packer builds Docker containers _without_ the use of 17 [Dockerfiles](https://docs.docker.com/reference/builder/). 18 By not using Dockerfiles, Packer is able to provision 19 containers with portable scripts or configuration management systems 20 that are not tied to Docker in any way. It also has a simpler mental model: 21 you provision containers much the same way you provision a normal virtualized 22 or dedicated server. For more information, read the section on 23 [Dockerfiles](#toc_8). 24 25 The Docker builder must run on a machine that has Docker installed. Therefore 26 the builder only works on machines that support Docker (modern Linux machines). 27 If you want to use Packer to build Docker containers on another platform, 28 use [Vagrant](http://www.vagrantup.com) to start a Linux environment, then 29 run Packer within that environment. 30 31 ## Basic Example: Export 32 33 Below is a fully functioning example. It doesn't do anything useful, since 34 no provisioners are defined, but it will effectively repackage an image. 35 36 ```javascript 37 { 38 "type": "docker", 39 "image": "ubuntu", 40 "export_path": "image.tar" 41 } 42 ``` 43 44 ## Basic Example: Commit 45 46 Below is another example, the same as above but instead of exporting the 47 running container, this one commits the container to an image. The image 48 can then be more easily tagged, pushed, etc. 49 50 ```javascript 51 { 52 "type": "docker", 53 "image": "ubuntu", 54 "commit": true 55 } 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) 67 can be configured for this builder. 68 69 ### Required: 70 71 * `commit` (boolean) - If true, the container will be committed to an 72 image rather than exported. This cannot be set if `export_path` is set. 73 74 * `export_path` (string) - The path where the final container will be exported 75 as a tar file. This cannot be set if `commit` is set to true. 76 77 * `image` (string) - The base image for the Docker container that will 78 be started. This image will be pulled from the Docker registry if it 79 doesn't already exist. 80 81 ### Optional: 82 83 * `login` (boolean) - Defaults to false. If true, the builder will 84 login in order to pull the image. The builder only logs in for the 85 duration of the pull. It always logs out afterwards. 86 87 * `login_email` (string) - The email to use to authenticate to login. 88 89 * `login_username` (string) - The username to use to authenticate to login. 90 91 * `login_password` (string) - The password to use to authenticate to login. 92 93 * `login_server` (string) - The server address to login to. 94 95 * `pull` (boolean) - If true, the configured image will be pulled using 96 `docker pull` prior to use. Otherwise, it is assumed the image already 97 exists and can be used. This defaults to true if not set. 98 99 * `run_command` (array of strings) - An array of arguments to pass to 100 `docker run` in order to run the container. By default this is set to 101 `["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. 102 As you can see, you have a couple template variables to customize, as well. 103 104 * `volumes` (map of strings to strings) - A mapping of additional volumes 105 to mount into this container. The key of the object is the host path, 106 the value is the container path. 107 108 ## Using the Artifact: Export 109 110 Once the tar artifact has been generated, you will likely want to import, tag, 111 and push it to a container repository. Packer can do this for you automatically 112 with the [docker-import](/docs/post-processors/docker-import.html) and 113 [docker-push](/docs/post-processors/docker-push.html) post-processors. 114 115 **Note:** This section is covering how to use an artifact that has been 116 _exported_. More specifically, if you set `export_path` in your configuration. 117 If you set `commit`, see the next section. 118 119 The example below shows a full configuration that would import and push 120 the created image: 121 122 ```javascript 123 { 124 "post-processors": [ 125 [ 126 { 127 "type": "docker-import", 128 "repository": "mitchellh/packer", 129 "tag": "0.7" 130 }, 131 "docker-push" 132 ] 133 ] 134 } 135 ``` 136 137 If you want to do this manually, however, perhaps from a script, you can 138 import the image using the process below: 139 140 ```text 141 $ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar 142 ``` 143 144 You can then add additional tags and push the image as usual with `docker tag` 145 and `docker push`, respectively. 146 147 ## Using the Artifact: Committed 148 149 If you committed your container to an image, you probably want to tag, 150 save, push, etc. Packer can do this automatically for you. An example is 151 shown below which tags and pushes the image: 152 153 ```javascript 154 { 155 "post-processors": [ 156 [ 157 { 158 "type": "docker-tag", 159 "repository": "mitchellh/packer", 160 "tag": "0.7" 161 }, 162 "docker-push" 163 ] 164 ] 165 } 166 ``` 167 168 ## Dockerfiles 169 170 This builder allows you to build Docker images _without_ Dockerfiles. 171 172 With this builder, you can repeatably create Docker images without the use of 173 a Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. 174 Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, 175 etc. to provision your Docker container just like you would a regular 176 virtualized or dedicated machine. 177 178 While Docker has many features, Packer views Docker simply as an LXC 179 container runner. To that end, Packer is able to repeatably build these 180 LXC containers using portable provisioning scripts. 181 182 Dockerfiles have some additional features that Packer doesn't support 183 which are able to be worked around. Many of these features will be automated 184 by Packer in the future: 185 186 * Dockerfiles will snapshot the container at each step, allowing you to 187 go back to any step in the history of building. Packer doesn't do this yet, 188 but inter-step snapshotting is on the way. 189 190 * Dockerfiles can contain information such as exposed ports, shared 191 volumes, and other metadata. Packer builds a raw Docker container image 192 that has none of this metadata. You can pass in much of this metadata 193 at runtime with `docker run`.