Configuring Docker Provisioner

1. Pulling Docker Images

Option	Values	Description
docker.image	`nginx:latest`	Name of the Docker image to pull
docker.pull	`true`	Whether to pull the image from Docker Hub or use local
docker.tag	`latest`	Tag of the Docker image to pull

Example: Pulling a Docker Image

Vagrant.configure("2") do |config|
  config.vm.provision "docker" do |d|
    d.pull = true
    d.image = "nginx:latest"
  end
end

2. Building from Dockerfile

Option	Values	Description
dockerfile	`string`	Path to the Dockerfile to build from. Defaults to `Dockerfile` in the project root.
build_args	`object`	Build arguments to pass to the Docker build command. Example: `{ "ARG1": "value1" }`
image	`string`	Name of the image to build. If not specified, a default name is generated.

Example: Building a Docker image from a custom Dockerfile

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.build_image "./custom/Dockerfile"
    d.image = "myapp:latest"
  end
end

Note: The Dockerfile must be located in the project directory or a subdirectory.

3. Running Containers

Option	Values	Notes
docker.container	`true`	Run a container instead of a VM
docker.image	`"nginx:latest"`	Base image to use for the container
docker.port_map	`[80:80]`	Port mapping from host to container
docker.volumes	`["/host/path:/container/path"]`	Volume mounts to bind host directories

Example: Running a Web Server Container

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.image = "nginx:latest"
    d.port_map = ["8080:80"]
    d.volumes = ['/var/www:/usr/share/nginx/html']
  end
end

4. Setting Container Options

Option	Values	Description
image	`string`	Name of the Docker image to use for the container
name	`string`	Name to assign to the running container
port_map	`array`	Array of port mappings in format `[host_port:container_port]`
volume_map	`array`	Array of volume mappings in format `[host_path:container_path]`
env_vars	`object`	Environment variables to set inside the container
command	`string`	Override the default command of the container image
privileged	`boolean`	Run container in privileged mode (default: `false`)

Example: Basic Container Configuration

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.image = "nginx:latest"
    d.name = "web-server"
    d.port_map = ["80:80"]
    d.env_vars = {
      "ENV" => "production"
    }
  end
end

Example: Volume and Command Override

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.image = "mysql:8.0"
    d.name = "db-container"
    d.volume_map = ["/host/data:/var/lib/mysql"]
    d.command = "--default-authentication-plugin=mysql_native_password"
    d.privileged = true
  end
end

5. Configuring Port Mappings

Option	Values	Description
config.vm.network	`"forwarded_port"`	Defines a port mapping between host and guest machine
guest	`80`	Port number inside the guest machine
host	`8080`	Port number on the host machine
id	`"http"`	Unique identifier for the forwarded port
auto_correct	`true`	Automatically correct port conflicts if possible
protocol	`"tcp"`	Protocol to use for the forwarded port (tcp/udp)

Example: Forwarding HTTP traffic

Vagrant.configure("2") do |config|
  config.vm.network "forwarded_port", guest: 80, host: 8080, id: "http"
end

Example: Forwarding multiple ports

Vagrant.configure("2") do |config|
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.network "forwarded_port", guest: 443, host: 8443
  config.vm.network "forwarded_port", guest: 5432, host: 5432
end

6. Mounting Volumes

Option	Values	Description
volume	`string`	Source path to mount (e.g., `/host/path` or `volume-name`)
destination	`string`	Target path inside the container (e.g., `/app`)
type	`bind` or `volume`	Mount type: `bind` for host paths, `volume` for named volumes
options	`string[]`	Mount options (e.g., `["ro"]`, `["Z"]`)

Example: Mounting a Host Directory

Vagrant.configure("2") do |config|
  config.vm.provision "docker" do |d|
    d.image = "nginx"
    d.mounts = [
      {
        volume: "/host/app",
        destination: "/usr/share/nginx/html",
        type: "bind"
      }
    ]
  end
end

Example: Using Named Volume

Vagrant.configure("2") do |config|
  config.vm.provision "docker" do |d|
    d.image = "postgres"
    d.mounts = [
      {
        volume: "db-data",
        destination: "/var/lib/postgresql/data",
        type: "volume"
      }
    ]
  end
end

Note: The mounts option requires Vagrant version 2.2.0 or later.

7. Using Docker Compose

Option	Values	Description
compose_file	`docker-compose.yml`	Path to the Docker Compose file to use
compose_options	`""`	Additional options to pass to docker-compose command

Example: Using Docker Compose with Vagrant

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.compose_file = "docker-compose.yml"
    d.compose_options = "--verbose"
  end
end

Note: Ensure that docker-compose is installed on the guest machine or use a Vagrant box with Docker Compose pre-installed.

8. Setting Environment Variables

Variable	Description	Example
env	Environment variables to set in the container	`{ "env": { "NODE_ENV": "production", "DATABASE_URL": "postgres://user:pass@localhost/db" } }`

Example: Setting Environment Variables in Docker Provisioner

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.env = {
      "NODE_ENV" => "production",
      "DATABASE_URL" => "postgres://user:pass@localhost/db"
    }
  end
end

9. Configuring Network Mode

Option	Values	Description
network_mode	`"bridge"`, `"host"`, `"none"`	Specifies the network mode for the container. Default is `"bridge"`.
network_mode	`"container:<name>"`	Shares the network namespace with another container. Requires the name of the container to share with.

Example: Setting Network Mode to Host

Vagrant.configure("2") do |config|
  config.vm.provision :docker do |d|
    d.network_mode = "host"
  end
end

Note: Using network_mode = "host" gives the container direct access to the host's network stack, which can be useful for performance but reduces isolation.

10. Using Post-Installation Commands

Command	Description	Example
post_install	Runs after the Docker container is created and started	`config.vm.provision "docker" do \|d\| d.post_install = "echo 'Post-installation complete'" end`
post_install_script	Path to a script file to run after container creation	`config.vm.provision "docker" do \|d\| d.post_install_script = "/path/to/post-install.sh" end`

Example: Running a Post-Installation Script

#!/bin/bash
echo "Running post-installation steps..."
# Install additional packages or configure services
apt-get update && apt-get install -y curl

Note: The post_install command runs in the context of the provisioner, which means it has access to the same environment as the Docker container.