» Docker Provisioner

Provisioner name: "docker"

The Vagrant Docker provisioner can automatically installDocker, pull Docker containers, and configure certaincontainers to run on boot.

The docker provisioner is ideal for organizations that are usingDocker as a means to distribute things like their application or services.Or, if you are just getting started with Docker, the Docker provisionerprovides the easiest possible way to begin using Docker since the provisionerautomates installing Docker for you.

As with all provisioners, the Docker provisioner can be used along withall the other provisioners Vagrant has in order to setup your workingenvironment the best way possible. For example, perhaps you use Puppet toinstall services like databases or web servers but use Docker to houseyour application runtime. You can use the Puppet provisioner alongwith the Docker provisioner.

Note: This documentation is for the Docker provisioner. If you are looking for the Dockerprovider, visit theDocker provider documentation.

» Options

The docker provisioner takes various options. None are required. Ifno options are required, the Docker provisioner will only install Dockerfor you (if it is not already installed).

  • images (array) - A list of images to pull using docker pull. Youcan also use the pull_images function. See the example below thissection for more information.In addition to the options that can be set, various functions are availableand can be called to configure other aspects of the Docker provisioner. Mostof these functions have examples in more detailed sections below.

  • build_image - Build an image from a Dockerfile.

  • pull_images - Pull the given images. This does not start these images.

  • post_install_provisioner - A provisioner block that runs post dockerinstallation.

  • run - Run a container and configure it to start on boot. This canonly be specified once.

» Building Images

The provisioner can automatically build images. Images are built prior toany configured containers to run, so you can build an image before running it.Building an image is easy:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.build_image "/vagrant/app"
  4.   end
  5. end

The argument to build an image is the path to give to docker build. Thismust be a path that exists within the guest machine. If you need to get datato the guest machine, use a synced folder.

The build_image function accepts options as a second parameter. Hereare the available options:

  • args (string) - Additional arguments to pass to docker build. Use thisto pass in things like -t "foo" to tag the image.

» Pulling Images

The docker provisioner can automatically pull images from theDocker registry for you. There are two ways to specify images topull. The first is as an array using images:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker",
  3.     images: ["ubuntu"]
  4. end

This will cause Vagrant to pull the "ubuntu" image from the registryfor you automatically.

The second way to pull images is to use the pullimages function.Each call to pull_images will _append the images to be pulled. Theimages variable, on the other hand, can only be used once.

Additionally, the pull_images function cannot be used with thesimple configuration method for provisioners (specifying it all in one line).

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.pull_images "ubuntu"
  4.     d.pull_images "vagrant"
  5.   end
  6. end

» Running Containers

In addition to pulling images, the Docker provisioner can run and startcontainers for you. This lets you automatically start services as part ofvagrant up.

Running containers can only be configured using the Ruby block syntax withthe do…end blocks. An example of running a container is shown below:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.run "rabbitmq"
  4.   end
  5. end

This will docker run a container with the "rabbitmq" image. Note thatVagrant uses the first parameter (the image name by default) to override anysettings used in a previous run definition. Therefore, if you need to runmultiple containers from the same image then you must specify the imageoption (documented below) with a unique name.

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 argumentbut can also be given here as an option.

  • cmd (string) - The command to start within the container. If not specified,then the container's default command will be used, such as the"CMD" command specified in the Dockerfile.

  • args (string) - Extra arguments for docker runon the command line. These are raw arguments that are passed directly to Docker.

  • auto_assign_name (boolean) - If true, the —name of the container willbe set to the first argument of the run. By default this is true. If thename set contains a "/" (because of the image name), it will be replacedwith "-". Therefore, if you do d.run "foo/bar", then the name of thecontainer will be "foo-bar".

  • daemonize (boolean) - If true, the "-d" flag is given to docker run todaemonize the containers. By default this is true.

  • restart (string) - The restart policy for the container. Defaults to"always"

For example, here is how you would configure Docker to run a containerwith the Vagrant shared directory mounted inside of it:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.run "ubuntu",
  4.       cmd: "bash -l",
  5.       args: "-v '/vagrant:/var/www'"
  6.   end
  7. end

In case you need to run multiple containers based off the same image, you can doso by providing different names and specifying the image parameter to it:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.run "db-1", image: "user/mysql"
  4.     d.run "db-2", image: "user/mysql"
  5.   end
  6. end

» Other

This section documents some other things related to the Docker provisionerthat are generally useful to know if you are using this provisioner.

» Customize /etc/default/docker

To customize this file, use the post_install_provisioner shell provisioner.

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "docker" do |d|
  3.     d.post_install_provision "shell", inline:"echo export http_proxy='http://127.0.0.1:3128/' >> /etc/default/docker"
  4.     d.run "ubuntu",
  5.       cmd: "bash -l",
  6.       args: "-v '/vagrant:/var/www'"
  7.   end
  8. end