Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Providers and Plugins

The Docker Provider

Use Vagrant's Docker provider to start containers from a Vagrantfile, build images, link containers, and learn when containers beat full virtual machines.

A virtual machine boots a whole operating system. A container shares the host's kernel and starts a single process in an isolated environment, so it starts in a second or two and uses a fraction of the memory. Vagrant's Docker provider lets you keep the familiar Vagrantfile workflow (vagrant up, vagrant ssh, vagrant destroy) while the "machine" is a container.

This lesson explains how the provider works and where it fits. The Vagrantfiles are read-only examples because they need a Docker engine on your computer.

How it differs from a VM provider

With VirtualBox, config.vm.box names a base image of a full OS. With Docker you do not use a box. You name a container image, or you build one from a Dockerfile.

Ruby
Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.image = "nginx:1.27"
    d.ports = ["8080:80"]
    d.name  = "demo-nginx"
  end
end
TEXT
$ vagrant up --provider=docker
Bringing machine 'default' up with 'docker' provider...
==> default: Creating the container...
    default:   Name: demo-nginx
    default:  Image: nginx:1.27
    default: Volume: /home/me/project:/vagrant
==> default: Starting container...

Port forwarding is declared inside the provider block as "host:container" strings. Your project folder is mounted at /vagrant just like a synced folder.

On macOS and Windows the Docker engine itself runs inside a lightweight VM (Docker Desktop). Vagrant talks to that engine; on those systems the speed advantage is smaller than on Linux, but the workflow is the same.

Building from a Dockerfile

When you need your own image, point the provider at a build directory.

Ruby
Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.build_dir = "."                  # directory containing the Dockerfile
    d.build_args = ["--build-arg", "APP_ENV=development"]
    d.ports = ["3000:3000"]
    d.env = { "NODE_ENV" => "development" }
    d.remains_running = true
  end
end
  • remains_running should be true for long-running servers. Vagrant treats a container that exits as a failure unless you set it to false (for one-off jobs).
  • d.env sets environment variables.
  • d.cmd overrides the image's default command, for example ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"].

Containers that look like VMs

Most official images run one process and have no SSH daemon, so vagrant ssh would fail. You have two choices.

  1. Use vagrant docker-exec or vagrant docker-run to enter or run commands.
  2. Use an image that runs SSH. The community maintains such images; set d.has_ssh = true.
TEXT
$ vagrant docker-exec -it -- /bin/sh
# ls /vagrant
Dockerfile  Vagrantfile  app.js
$ vagrant docker-logs
$ vagrant docker-run -- node --version

Because containers are designed to run one service, they pair well with multi-machine Vagrantfiles: one container for the app, one for the database.

Ruby
Vagrant.configure("2") do |config|
  config.vm.define "db" do |db|
    db.vm.provider "docker" do |d|
      d.image = "postgres:16"
      d.name  = "app-db"
      d.env   = { "POSTGRES_PASSWORD" => "devpass" }
    end
  end

  config.vm.define "web" do |web|
    web.vm.provider "docker" do |d|
      d.build_dir = "./web"
      d.link("app-db:db")        # makes the host name "db" resolvable in web
      d.ports = ["8080:8000"]
    end
  end
end

d.link("container:alias") makes the other container reachable by its alias. It is legacy Docker behavior; for new projects, a user-defined Docker network or Docker Compose is cleaner, and Vagrant itself ships a Compose-friendly flow by letting you run docker compose in a shell provisioner. For anything beyond a few containers, use Compose directly.

Host VM for non-Linux hosts

If you want a Linux Docker engine (not Docker Desktop), set a Vagrant-managed VM as the Docker host. Vagrant boots the VM, installs Docker, then starts your containers inside it.

Ruby
Vagrant.configure("2") do |config|
  config.vm.provider "docker" do |d|
    d.vagrant_vagrantfile = "../docker-host/Vagrantfile"
    d.image = "redis:7"
    d.ports = ["6379:6379"]
  end
end

vagrant_vagrantfile points to a second Vagrantfile that defines the host VM. One vagrant up starts both.

A stand-in: turning provider settings into a docker run command

A container definition is data that turns into a command line. This Ruby stand-in builds the equivalent docker run string so you can see what the provider asks Docker to do. It does not start anything; it is plain Ruby.

Ruby From provider block to docker run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

When to choose containers

Choose the Docker provider when you need a quick, disposable process: a web server, a database, a message queue. Choose a VM provider when you need a full OS: systemd services, kernel modules, firewalls, multiple users, or software that expects to own the machine. Many teams use both: VMs to practice server administration, containers for application dependencies. The final lesson of this chapter group compares them at length in Vagrant versus Docker and alternatives.

Common mistakes

  • Expecting vagrant ssh to work on a stock image with no SSH daemon.
  • A container that exits immediately. If the main process ends, Vagrant reports failure; keep a foreground process or use remains_running = false on purpose.
  • Mixing config.vm.box with the Docker provider. Boxes are for VM providers; use d.image or d.build_dir.
  • Storing data inside the container. It disappears on vagrant destroy; mount a volume or use the synced folder.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do you use instead of config.vm.box with the Docker provider?

    Docker needs a container image, either named with image or built from a Dockerfile directory.
  2. 2. Why does a container that runs a one-off command make vagrant up report failure?

    By default Vagrant treats a container that exits as an error; set remains_running = false for short jobs.
  3. 3. How can you get a shell in a stock nginx container started by Vagrant?

    Most images have no SSH daemon, so use docker-exec instead.
  4. 4. Which workload is the better fit for a full VM provider than for Docker?

    Systemd, firewalls and multi-user administration need a full operating system.

Summary

  • The Docker provider runs containers from an image or a Dockerfile instead of booting a box.
  • Ports, environment variables, commands and links are set in the config.vm.provider "docker" block.
  • Use vagrant docker-exec, docker-logs and docker-run because most images lack SSH.
  • Pick containers for quick, single-service needs and VMs when you need a full OS.

Next: Vagrant plugins