website/docs: document the Docker provisioner

website/docs/source/layouts/layout.erb

@@ -150,6 +150,7 @@
 									<li<%= sidebar_current("provisioning-ansible") %>><a href="/v2/provisioning/ansible.html">Ansible</a></li>
 									<li<%= sidebar_current("provisioning-chefsolo") %>><a href="/v2/provisioning/chef_solo.html">Chef Solo</a></li>
 									<li<%= sidebar_current("provisioning-chefclient") %>><a href="/v2/provisioning/chef_client.html">Chef Client</a></li>
+									<li<%= sidebar_current("provisioning-docker") %>><a href="/v2/provisioning/docker.html">Docker</a></li>
 									<li<%= sidebar_current("provisioning-puppetapply") %>><a href="/v2/provisioning/puppet_apply.html">Puppet Apply</a></li>
 									<li<%= sidebar_current("provisioning-puppetagent") %>><a href="/v2/provisioning/puppet_agent.html">Puppet Agent</a></li>
 									<li<%= sidebar_current("provisioning-salt") %>><a href="/v2/provisioning/salt.html">Salt</a></li>

website/docs/source/v2/provisioning/docker.html.md

@@ -0,0 +1,112 @@
+---
+page_title: "Docker - Provisioning"
+sidebar_current: "provisioning-docker"
+---
+
+# Docker Provisioner
+
+**Provisioner name: `"docker"`**
+
+The docker provisioner can automatically install [Docker](http://www.docker.io),
+pull Docker containers, and configure certain containers to run on boot.
+
+The docker provisioner is ideal for organizations that are using
+Docker as a means to distribute things like their application or services.
+Or, if you're just getting started with Docker, the Docker provisioner
+provides the easiest possible way to begin using Docker since the provisioner
+automates installing Docker for you.
+
+As with all provisioners, the Docker provisioner can be used along with
+all the other provisioners Vagrant has in order to setup your working
+environment the best way possible. For example, perhaps you use Puppet to
+install services like databases or web servers but use Docker to house
+your application runtime. You can use the Puppet provisioner along
+with the Docker provisioner.
+
+## Options
+
+The docker provisioner takes various options. None are required. If
+no options are required, the Docker provisioner will only install Docker
+for you (if it isn't already installed).
+
+* `images` (array) - A list of images to pull using `docker pull`. You
+  can also use the `pull_images` function. See the example below this
+  section for more information.
+
+* `version` (string) - The version of Docker to install. This defaults to
+  "latest" and will install the latest version of Docker.
+
+## Pulling Images
+
+The docker provisioner can automatically pull images from the
+Docker registry for you. There are two ways to specify images to
+pull. The first is as an array using `images`:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "docker",
+    images: ["ubuntu"]
+end
+```
+
+This will cause Vagrant to pull the "ubuntu" image from the registry
+for you automatically.
+
+The second way to pull images is to use the `pull_images` function.
+Each call to `pull_images` will _append_ the images to be pulled. The
+`images` variable, on the other hand, can only be used once.
+
+Additionally, the `pull_images` function cannot be used with the
+simple configuration method for provisioners (specifying it all in one line).
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.pull_images "ubuntu"
+    d.pull_images "vagrant"
+  end
+end
+```
+
+## Running Containers
+
+In addition to pulling images, the Docker provisioner can run and start
+containers for you. This lets you automatically start services as part of
+`vagrant up`.
+
+Running containers can only be configured using the Ruby block syntax with
+the `do...end` blocks. An example of running a container is shown below:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.run "rabbitmq"
+  end
+end
+```
+
+This will `docker run` a container with the "rabbitmq" image. In addition
+to the name, the `run` method accepts a set of options, all optional:
+
+* `image` (string) - The image to run. This defaults to the first argument
+  but can also be given here as an option.
+
+* `cmd` (string) - The command to start within the container. If not specified,
+  then the containers default "run" command will be used, such as the
+  "run" command specified when the container was built.
+
+* `args` (string) - Extra arguments for `docker run` on the command line.
+  These are raw arguments that are passed directly to Docker.
+
+For example, here is how you would configure Docker to run a container
+with the Vagrant shared directory mounted inside of it:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.run "ubuntu",
+      cmd: "bash -l",
+      args: "-v '/vagrant:/var/www'"
+  end
+end
+```