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`.