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

---
page_title: "Basic Usage - Docker Provider"
sidebar_current: "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](/v2/docker/images.html) or
built from a [Dockerfile](/v2/docker/dockerfiles.html), 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:

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

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:

<pre class="prettyprint">
Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.build_dir = "."
  end
end
</pre>

The above configuration will look for a `Dockerfile` in the same
directory as the Vagrantfile. When `vagrant up --provider=docker` 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](https://github.com/mitchellh/vagrant/blob/master/plugins/providers/docker/hostmachine/Vagrantfile),
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.

<div class="alert alert-info">
	<strong>Synced folder note:</strong> 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.
</div>

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:

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

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](/v2/cli/global-status.html)
along with global control.