» Docker Basic Usage

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

The Docker provider does not require a config.vm.box setting. Sincethe "base image" for a Docker container is pulled from theDocker Index orbuilt from a Dockerfile, the box does notadd much value, and is optional for this provider.

» Docker Images

The first method that Vagrant can use to source a Docker containeris via an image. This image can be from any Docker registry. Anexample 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 theimage foo/bar.

This is useful for extra components of your application that it mightdepend on: databases, queues, etc. Typically, the primary applicationyou are working on is built with a Dockerfile, or via a container withSSH.

» Dockerfiles

Vagrant can also automatically build and run images based on a localDockerfile. This is useful for iterating on an application locallythat 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 samedirectory as the Vagrantfile. When vagrant up —provider=docker is run, Vagrantautomatically builds that Dockerfile and starts a containerbased on that Dockerfile.

The Dockerfile is rebuilt when vagrant reload is called.

» Synced Folders and Networking

When using Docker, Vagrant automatically converts synced foldersand networking options into Docker volumes and forwarded ports.You do not have to use the Docker-specific configurations to do this.This helps keep your Vagrantfile similar to how it has always looked.

The Docker provider does not support specifying options for owner or groupon folders synced with a docker container.

» Volume Consistency

Docker's volume consistency setting can be specified using the docker_consistency option when defining a synced folder. This cangreatly improve performance on macOS. An example is shown using the cached and delegated settings:

config.vm.synced_folder "/host/dir1", "/guest/dir1", docker_consistency: "cached"
config.vm.synced_folder "/host/dir2", "/guest/dir2", docker_consistency: "delegated"

» Host VM

If the system cannot run Linux containers natively, Vagrant automatically spinsup a "host VM" to run Docker. This allows your Docker-based Vagrant environmentsto remain portable, without inconsistencies depending on the platform they arerunning on.

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

By default, the host VM Vagrant spins up isbacked by boot2docker,because it launches quickly and uses little resources. But the host VMcan be customized to point to any Vagrantfile. This allows the host VMto 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 isoften rsync. In this case, make sure you have rsync installed on yourhost machine. Vagrant will give you a human-friendly error message ifit is not.

An example of changing the host VM is shown below. Remember that thisis optional, and Vagrant will spin up a default host VM if it is notspecified:

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 provideris Docker. To control this host VM, use theglobal-status commandalong with global control.