diff --git a/website/source/docs/builders/docker.html.markdown b/website/source/docs/builders/docker.html.markdown index c3f9f8018..3e0b9f89a 100644 --- a/website/source/docs/builders/docker.html.markdown +++ b/website/source/docs/builders/docker.html.markdown @@ -10,7 +10,20 @@ The Docker builder builds [Docker](http://www.docker.io) images using Docker. The builder starts a Docker container, runs provisioners within this container, then exports the container for re-use. -The Docker builder must run on a machine that supports Docker. +Packer builds Docker containers _without_ the use of +[Dockerfiles](http://docs.docker.io/en/latest/use/builder/). +By not using Dockerfiles, Packer is able to provision +containers with portable scripts or configuration management systems +that are not tied to Docker in any way. It also has a simpler mental model: +you provision containers much the same way you provision a normal virtualized +or dedicated server. For more information, read the section on +[Dockerfiles](#toc_3). + +The Docker builder must run on a machine that has Docker installed. Therefore +the builder only works on machines that support Docker (modern Linux machines). +If you want to use Packer to build Docker containers on another platform, +use [Vagrant](http://www.vagrantup.com) to start a Linux environment, then +run Packer within that environment. ## Basic Example @@ -47,11 +60,32 @@ Optional: ## Dockerfiles -This builder allows you to build Docker images _without_ Dockerfiles. If -you have a Dockerfile already made, it is simple to just run `docker build` -manually. +This builder allows you to build Docker images _without_ Dockerfiles. With this builder, you can repeatably create Docker images without the use a Dockerfile. You don't need to know the syntax or semantics of Dockerfiles. Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, -etc. to provision your Docker container just like you would a regular machine. +etc. to provision your Docker container just like you would a regular +virtualized or dedicated machine. + +While Docker has many features, Packer views Docker simply as an LXC +container runner. To that end, Packer is able to repeatably build these +LXC containers using portable provisioning scripts. + +Dockerfiles have some additional features that Packer doesn't support +which are able to be worked around. Many of these features will be automated +by Packer in the future: + +* Dockerfiles will snapshot the container at each step, allowing you to + go back to any step in the history of building. Packer doesn't do this yet, + but inter-step snapshotting is on the way. + +* Dockerfiles can contain information such as exposed ports, shared + volumes, and other metadata. Packer builds a raw Docker container image + that has none of this metadata. You can pass in much of this metadata + at runtime with `docker run`. + +* Images made without dockerfiles are missing critical metadata that + make them easily pushable to the Docker registry. You can work around + this by using a metadata-only Dockerfile with the exported image and + building that. A future Packer version will automatically do this for you.