vagrant/website/docs/source/v2/docker/basics.html.md

page_title	sidebar_current
Basic Usage - Docker Provider	docker-basics

Docker Basic Usage

The Docker provider in Vagrant behaves just like any other provider. If you're familiar with Vagrant already, then using the Docker provider should be intuitive and simple.

The Docker provider does not require a config.vm.box setting. Since the "base image" for a Docker container is pulled from the Docker Index or built from a Dockerfile, the box doesn't add much value, and is optional for this provider.

Docker Images

The first method that Vagrant can use to source a Docker container is via an image. This image can be from any Docker registry. An example is shown below:

Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.image = "foo/bar"
  end
end

When vagrant up --provider=docker is run, this will bring up the image foo/bar.

This is useful for extra components of your application that it might depend on: databases, queues, etc. Typically, the primary application you're working on is built with a Dockerfile, or via a container with SSH.

Dockerfiles

Vagrant can also automatically build and run images based on a local Dockerfile. This is useful for iterating on an application locally that is built into an image later. An example is shown below:

Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.build_dir = "."
  end
end

The above configuration will look for a Dockerfile in the same directory as the Vagrantfile. When vagrant up is run, Vagrant automatically builds that Dockerfile and starts a container based on that Dockerfile.

The Dockerfile is rebuilt when vagrant reload is called.

Host VM

On systems that can't run Linux containers natively, such as Mac OS X or Windows, Vagrant automatically spins up a "host VM" to run Docker. This allows your Docker-based Vagrant environments to remain portable, without inconsistencies depending on the platform they are running on.

Vagrant will spin up a single instance of a host VM and run multiple containers on this one VM. This means that with the Docker provider, you only have the overhead of one virtual machine, and only if it is absolutely necessary.

By default, the host VM Vagrant spins up is backed by boot2docker, because it launches quickly and uses little resources. But the host VM can be customized to point to any Vagrantfile. This allows the host VM to more closely match production by running a VM running Ubuntu, RHEL, etc. It can run any operating system supported by Vagrant.

Synced folder note: Vagrant will attempt to use the "best" synced folder implementation it can. For boot2docker, this is often rsync. In this case, make sure you have rsync installed on your host machine. Vagrant will give you a human-friendly error message if it isn't.

An example of changing the host VM is shown below. Remember that this is optional, and Vagrant will spin up a default host VM if it isn't specified:

Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.vagrant_vagrantfile = "../path/to/Vagrantfile"
  end
end

The host VM will be spun up at the first vagrant up where the provider is Docker. To control this host VM, use the global-status command along with global control.