github.com/kaixiang/packer@v0.5.2-0.20140114230416-1f5786b0d7f1/website/source/docs/builders/docker.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  ---
     4  
     5  # Docker Builder
     6  
     7  Type: `docker`
     8  
     9  The Docker builder builds [Docker](http://www.docker.io) images using
    10  Docker. The builder starts a Docker container, runs provisioners within
    11  this container, then exports the container for re-use.
    12  
    13  Packer builds Docker containers _without_ the use of
    14  [Dockerfiles](http://docs.docker.io/en/latest/use/builder/).
    15  By not using Dockerfiles, Packer is able to provision
    16  containers with portable scripts or configuration management systems
    17  that are not tied to Docker in any way. It also has a simpler mental model:
    18  you provision containers much the same way you provision a normal virtualized
    19  or dedicated server. For more information, read the section on
    20  [Dockerfiles](#toc_4).
    21  
    22  The Docker builder must run on a machine that has Docker installed. Therefore
    23  the builder only works on machines that support Docker (modern Linux machines).
    24  If you want to use Packer to build Docker containers on another platform,
    25  use [Vagrant](http://www.vagrantup.com) to start a Linux environment, then
    26  run Packer within that environment.
    27  
    28  ## Basic Example
    29  
    30  Below is a fully functioning example. It doesn't do anything useful, since
    31  no provisioners are defined, but it will effectively repackage an image.
    32  
    33  <pre class="prettyprint">
    34  {
    35    "type": "docker",
    36    "image": "ubuntu",
    37    "export_path": "image.tar"
    38  }
    39  </pre>
    40  
    41  ## Configuration Reference
    42  
    43  Configuration options are organized below into two categories: required and
    44  optional. Within each category, the available options are alphabetized and
    45  described.
    46  
    47  Required:
    48  
    49  * `export_path` (string) - The path where the final container will be exported
    50    as a tar file.
    51  
    52  * `image` (string) - The base image for the Docker container that will
    53    be started. This image will be pulled from the Docker registry if it
    54    doesn't already exist.
    55  
    56  Optional:
    57  
    58  * `pull` (bool) - If true, the configured image will be pulled using
    59    `docker pull` prior to use. Otherwise, it is assumed the image already
    60    exists and can be used. This defaults to true if not set.
    61  
    62  * `run_command` (array of strings) - An array of arguments to pass to
    63    `docker` in order to run the container. By default this is set to
    64    `["run", "-d", "-i", "-t", "-v", "{{.Volumes}}", "{{.Image}}", "/bin/bash"]`.
    65    As you can see, you have a couple template variables to customize, as well.
    66  
    67  ## Using the generated artifact
    68  
    69  Once the tar artifact has been generated, you will likely want to import, tag,
    70  and push it to a container repository. Until packer supports management of the
    71  docker image metadata, this process is manual. For example, the following will
    72  import `mycontainer-123456789.tar` to the repository
    73  `registry.mydomain.com/mycontainer`, tagged with `latest`:
    74  
    75      sudo docker import - registry.mydomain.com/mycontainer:latest < mycontainer-123456789.tar
    76  
    77  You can then add additional tags and push the image as usual with `docker tag`
    78  and `docker push`, respectively.
    79  
    80  ## Dockerfiles
    81  
    82  This builder allows you to build Docker images _without_ Dockerfiles.
    83  
    84  With this builder, you can repeatably create Docker images without the use
    85  a Dockerfile. You don't need to know the syntax or semantics of Dockerfiles.
    86  Instead, you can just provide shell scripts, Chef recipes, Puppet manifests,
    87  etc. to provision your Docker container just like you would a regular
    88  virtualized or dedicated machine.
    89  
    90  While Docker has many features, Packer views Docker simply as an LXC
    91  container runner. To that end, Packer is able to repeatably build these
    92  LXC containers using portable provisioning scripts.
    93  
    94  Dockerfiles have some additional features that Packer doesn't support
    95  which are able to be worked around. Many of these features will be automated
    96  by Packer in the future:
    97  
    98  * Dockerfiles will snapshot the container at each step, allowing you to
    99    go back to any step in the history of building. Packer doesn't do this yet,
   100    but inter-step snapshotting is on the way.
   101  
   102  * Dockerfiles can contain information such as exposed ports, shared
   103    volumes, and other metadata. Packer builds a raw Docker container image
   104    that has none of this metadata. You can pass in much of this metadata
   105    at runtime with `docker run`.
   106  
   107  * Images made without dockerfiles are missing critical metadata that
   108    make them easily pushable to the Docker registry. You can work around
   109    this by using a metadata-only Dockerfile with the exported image and
   110    building that. A future Packer version will automatically do this for you.