Setting up a realistic, multi-machine environment on your own laptop used to mean juggling VirtualBox windows, clicking through installers, and hoping you could reproduce the same setup tomorrow. Vagrant replaces all of that with a single text file.

In this article we'll build a three-machine lab, two Ubuntu web servers and one CentOS database server, wired together on a private network, with the database node automatically provisioned at boot.

By the end you'll understand not just what the configuration says, but why each line is there and what can go wrong.

What We're Building

The target topology is simple but representative of a real application stack:

All three machines sit on the same host-only private network (192.168.56.0/24), which lets them talk to each other while staying isolated from the outside world. The database node, db01, gets a provisioning script that sets its hostname, populates /etc/hosts, and installs a running MariaDB instance — so the moment vagrant up finishes, the box is ready to accept connections.

A Quick Word on Vagrant

Vagrant is an infrastructure-as-code tool for managing virtual machines. You describe the machines you want in a file called a Vagrantfile, and Vagrant talks to a provider (VirtualBox by default) to create them. The two ideas that make Vagrant powerful are boxes and provisioners.

A box is a pre-packaged base image, for example ubuntu/focal64 is a minimal Ubuntu 20.04 install. Instead of running an OS installer, Vagrant downloads the box once and clones it for each machine. A provisioner is the code that runs the first time a machine boots (and again on demand), turning a generic base image into the specific server you need. Together they give you environments that are disposable, repeatable, and version-controllable.

The Complete Vagrantfile

Here is the configuration in full. We'll dissect it section by section afterward.

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|

  # ---------------------------------------------------------------
  # web01 - Ubuntu 20.04 (Focal Fossa)
  # ---------------------------------------------------------------
  config.vm.define "web01" do |web01|
    web01.vm.box = "ubuntu/focal64"
    web01.vm.hostname = "web01"
    web01.vm.network "private_network", ip: "192.168.56.11"
  end

  # ---------------------------------------------------------------
  # web02 - Ubuntu 20.04 (Focal Fossa)
  # ---------------------------------------------------------------
  config.vm.define "web02" do |web02|
    web02.vm.box = "ubuntu/focal64"
    web02.vm.hostname = "web02"
    web02.vm.network "private_network", ip: "192.168.56.12"
  end

  # ---------------------------------------------------------------
  # db01 - CentOS 7  (with provisioning + hostname configuration)
  # ---------------------------------------------------------------
  config.vm.define "db01" do |db01|
    db01.vm.box = "centos/7"
    db01.vm.hostname = "db01"
    db01.vm.network "private_network", ip: "192.168.56.13"

    # Provisioning for db01
    db01.vm.provision "shell", inline: <<-SHELL
      echo "==== Provisioning db01 ===="

      # Ensure hostname is configured persistently
      hostnamectl set-hostname db01

      # Add host entries for the other VMs (handy for app -> db lookups)
      cat >> /etc/hosts <<-HOSTS
        192.168.56.11  web01
        192.168.56.12  web02
        192.168.56.13  db01
      HOSTS

      # Update packages and install MariaDB (MySQL) server
      yum update -y
      yum install -y mariadb-server mariadb

      # Enable and start the database service
      systemctl enable mariadb
      systemctl start mariadb

      echo "==== db01 provisioning complete ===="
    SHELL
  end

end

Breaking It Down

The configuration block

Vagrant.configure("2") do |config|
  ...
end

The Vagrantfile is written in Ruby, and everything lives inside a single configuration block. The "2" is the configuration version, version 2 has been the standard for years and covers every modern Vagrant release. The config object passed into the block is the handle through which you describe global settings and individual machines.

Defining multiple machines

The key to a multi-VM setup is config.vm.define. Each call carves out a named machine with its own nested configuration:

config.vm.define "web01" do |web01|
  ...
end

The name you pass ("web01") becomes the identifier you use on the command line, for example vagrant ssh web01 or vagrant provision db01. Inside the block you configure that machine in isolation, which is what lets web01, web02, and db01 run different operating systems and carry different settings within one file.

Choosing a box

web01.vm.box = "ubuntu/focal64"

ubuntu/focal64 is the official Ubuntu 20.04 LTS box (Focal Fossa is the 20.04 codename). The database node instead uses centos/7. Boxes are downloaded from Vagrant Cloud the first time they're needed and then cached locally, so subsequent machines using the same box start almost instantly.

Setting the hostname

web01.vm.hostname = "web01"

This tells Vagrant to set the machine's hostname during boot. It's a convenience that keeps your shell prompts readable and gives each box a stable identity. For db01 we also set the hostname inside the provisioning script with hostnamectl — more on why below.

Private networking

web01.vm.network "private_network", ip: "192.168.56.11"

A private_network creates a host-only network: the VMs can reach each other and the host machine, but they aren't directly exposed to the wider LAN or internet. Assigning static IPs in the same subnet (192.168.56.x) means web01 can always find db01 at 192.168.56.13, which is exactly what an application server needs to locate its database.

The 192.168.56.0/24 range matters. Recent versions of VirtualBox restrict which host-only networks are allowed for security reasons, and 192.168.56.0/21 is the default permitted range. Using an IP outside it will cause Vagrant to fail with a network validation error unless you explicitly whitelist the range in /etc/vbox/networks.conf.

Provisioning the database node

The most interesting part is the shell provisioner attached to db01:

db01.vm.provision "shell", inline: <<-SHELL
  ...
SHELL

The <<-SHELL ... SHELL syntax is a Ruby heredoc, a multi-line string that Vagrant uploads to the guest and runs as root on first boot. Walking through what it does:

Hostname configuration. hostnamectl set-hostname db01 writes the hostname persistently through systemd. Even though Vagrant's hostname setting already does this, calling hostnamectl inside the script makes the intent explicit and guarantees it survives regardless of box quirks, a small belt-and-suspenders habit that's common in real provisioning code.

Host resolution. The script appends entries to /etc/hosts so that names like web01 and web02 resolve to their private IPs from inside db01. In a lab without a DNS server, this is the simplest way to let machines refer to each other by name instead of memorizing addresses.

Package installation. yum update -y refreshes the package metadata, then yum install -y mariadb-server mariadb pulls in the MariaDB database engine (the community fork of MySQL that ships in the CentOS 7 repositories).

Service management. Finally, systemctl enable mariadb makes the database start automatically on every boot, and systemctl start mariadb brings it up immediately so you don't have to reboot to use it.

Running the Lab

With the Vagrantfile saved in an empty directory, the workflow is short:

# Bring up all three machines
vagrant up

# SSH into any machine by name
vagrant ssh db01

# Re-run only db01's provisioning after editing the script
vagrant provision db01

# Check the status of every machine
vagrant status

# Tear everything down when you're done
vagrant destroy -f

The first vagrant up will take a few minutes as boxes download and db01 runs its provisioning. Subsequent boots are much faster because the boxes are already cached.

Common Pitfalls

A few things tend to trip people up the first time they run a setup like this.

The CentOS 7 box is end-of-life. CentOS 7 reached end of life in mid-2024, and its package mirrors have been moving to the CentOS Vault. If yum update fails to reach a mirror, you may need to repoint yum at the vault URLs, or switch to a maintained box such as generic/centos7. For brand-new labs, consider Rocky Linux or AlmaLinux as drop-in CentOS successors.

Host-only network range. As noted earlier, if you pick IPs outside 192.168.56.0/21 you'll hit a VirtualBox validation error. Either stay within the default range or add your range to /etc/vbox/networks.conf.

Heredoc indentation. When you append to /etc/hosts using a nested heredoc, leading whitespace from the indented script lines is carried into the file. It's harmless for /etc/hosts parsing, but if you want perfectly clean entries, use <<-HOSTS with tab indentation (which the dash strips) or drop the indentation entirely.

Provisioning only runs once. By default, provisioners execute only on the first vagrant up or when you explicitly call vagrant provision. Editing the script and re-running vagrant up on an already-running machine won't re-provision it, use vagrant provision db01 or vagrant reload --provision.

Where to Go Next

This lab is a foundation. Natural extensions include adding provisioning to the two web servers so they install and start Nginx or Apache, configuring the web tier to connect to MariaDB on db01, securing the database with mysql_secure_installation, or moving from inline shell scripts to a configuration-management tool like Ansible once your provisioning logic grows beyond a handful of commands. You might also tune the VM resources (CPU and memory) per machine using a config.vm.provider block when the default allocation isn't enough.

The real value of expressing all of this in a Vagrantfile is reproducibility: anyone who clones your repository and runs vagrant up gets the exact same three-machine environment, every time, on any machine that has Vagrant and VirtualBox installed. That predictability is the whole point, and it's why a few dozen lines of Ruby can replace an afternoon of manual setup.