Vagrant is a tool that allows us to script the creation of a virtual machine (VM). It’s typically used for creating a VM to run on our local computer (rather than building a VM to run in the cloud).
Vagrant is a great way to create a Linux-based development environment. It’s also great for experimenting with new software (e.g., Docker and Terraform). You can use it so that you don’t clutter up your regular development computer with new software.
I used Vagrant extensively on a day-to-day basis for development until just recently. It was really useful as a convenient way to get Docker working on a computer running Windows 10 Home. Now, I use WSL2 (Windows Subsystem for Linux 2). Docker for Windows integrates with that (see chapter 3 for details), so I don’t need Vagrant to run Docker anymore.
But Vagrant is still useful for building throwaway environments for development, testing, and experimentation. You can find an example Vagrant setup on GitHub:
The example Vagrant setup installs Docker, Docker Compose, and Terraform automatically, giving you an “instant” development environment you can use to experiment with the code examples that accompany this book (see section A.6). Note that the example code repositories for the chapters of this book each include a preconfigured Vagrant script that you can use to run the code for that chapter.
A.1 Installing VirtualBox
Before using Vagrant, you must install VirtualBox. This is the software that actually runs the VM within your regular computer (the host). You can download it from the VirtualBox download page:
Download and install the package that fits your host operating system. Follow the instructions on the VirtualBox web page.
NOTE Vagrant supports other VM providers, like VMWare, but I recommend VirtualBox because it’s free and easy to setup.
A.2 Installing Vagrant
Now install Vagrant. This is a scripting layer on top of VirtualBox that allows you to manage the setup of your VM through code (Ruby code actually). You can download it from the Vagrant downloads page:
Download and install the package that fits your host operating system. Follow the instructions on the Vagrant web page.
A.3 Creating your virtual machine (VM)
With VirtualBox and Vagrant installed, you are now ready to create your VM. First, you must decide which operating system to use. If you already have a production system in place, choose that same operating system. If not, choose a long-term support (LTS) version that will hold up for a long time. You can search for operating systems on this web page:
I’m a big fan of Ubuntu Linux, so for this example, we’ll use Ubuntu 20.04 LTS. The Vagrant name for the box that we’ll install is ubuntu/xenial64.
Before creating the Vagrant box, open a command line and create a directory in which to store it. Change to that directory, then invoke the vagrant init command as follows:
vagrant init ubuntu/xenial64
This creates a barebones Vagrantfile in the current directory. Edit this file to change the configuration and setup for your VM. You can learn more about Vagrant configuration here:
vagrant up
Make sure you run this command in the same directory that contains the Vagrantfile. This can take some time, especially if you don’t already have the image for the operating system locally cached. Do give it plenty of time to complete. Once it has finished, you will have a fresh Ubuntu VM to work with.
A.4 Connecting to your VM
With the VM booted up, you can now connect to it like this:
vagrant ssh
Vagrant automatically creates an SSH key and manages the connection for you. You now have a command-line shell into your VM. Any commands you invoke in this shell are executed inside your VM.
A.5 Installing software in the VM
With your VM running and having connected using vagrant ssh, you’ll now want to install some software. The first thing to do with your new VM is to update the operating system. You can do this in Ubuntu with
sudo apt-get update
You can now install whatever software you need by following the instructions from the software vendor. To install Docker, see
To install Docker Compose, see
To install Terraform, you simply download it, unpack it, and add the executable to your path. You can download Terraform from here:
The example Vagrant setup (next section) installs all these tools automatically. This gives you an “instant” development environment you can use to experiment with the code examples that accompany this book.
A.6 Using the example setup
You can start a VM from the example setup on GitHub available at
Clone the repository using Git:
git clone https://github.com/bootstrapping-microservices/example-vagrant-vm
Then change to that repository directory:
cd example-vagrant-vm
vagrant up
Connect a command-line shell to the VM:
vagrant ssh
This Vagrant script runs a shell script that automatically installs Docker, Docker Compose, and Terraform! Once the VM has started and you have connected you can use all these tools.
A.7 Turning your VM off
After you have completely finished with your VM, you can destroy it with the following command:
vagrant destroy
If you are only temporarily finished with the machine and would like to reuse it again later, suspend it with the following command:
vagrant suspend
A suspended machine can be resumed at any time by invoking vagrant up. Remember to destroy or suspend your virtual machines when you are not using these, otherwise, they’ll unnecessarily consume your valuable system resources.