Install Vagrant

What Vagrant is

A tool that starts a whole computer inside your computer, described in a text file. The file is five lines long, and anyone who gets it can start exactly the same machine as you have. The same operating system, the same programs, the same settings.

The point becomes clear once there is more than one of you in the company. The classic problem is that something works on one computer but not on another, and nobody can say why. With Vagrant the answer is in the file. If it does not work, it does not work for anyone, and then you can troubleshoot for real.

The second use is daring to test things. The machine is a copy. If you destroy it, you tear it down and start a new one in a few minutes, and your real computer has not noticed a thing.

You need VirtualBox first

Vagrant does not start machines on its own, it tells another program to do it. That program is called a provider, and the most common one is VirtualBox, which is free. Install it before Vagrant, otherwise everything stops at the first command.

Download VirtualBox from virtualbox.org for Windows. On Linux Mint the package is called virtualbox and is installed with sudo apt-get install virtualbox.

One more thing about Windows: VirtualBox and WSL2 sometimes fight over the same feature in the computer, and if you already have Docker Desktop running, VirtualBox may refuse to start machines. Turn off Docker Desktop while you work with Vagrant, and you avoid hunting for the error.

Windows

Download the installer from hashicorp.com and run it. Then open PowerShell and check that it worked:

vagrant --version

If you get an error saying the command is not found, log out and log in again. That is almost always enough.

Linux Mint

Vagrant is in the publisher's own package repository. Open Terminal and run the lines in order:

wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt-get update && sudo apt-get install vagrant

Linux Mint is based on Ubuntu but has its own version names, and lsb_release -cs answers with Mint's name, for example wilma. That name is not in the repository. Replace it with the Ubuntu name that your Mint version is based on, which is in the file /etc/os-release on the line UBUNTU_CODENAME.

Three things to do first

1. Create a folder for the project and run vagrant init bento/ubuntu-24.04 in it. You get a file called Vagrantfile. Open it and read. It is mostly comments, and they explain more than most guides do.
2. Start the machine with vagrant up. The first time, an image of a couple of gigabytes is downloaded, so it takes a while. The next time it takes under a minute, because the image stays on disk.
3. Log in with vagrant ssh. Now you are in a Linux system that is not your own computer. Install something, break something, and then shut down with exit followed by vagrant destroy. Being able to throw it away is the whole point.

The most common trap

Believing that the files inside the machine are safe. The folder you are in on your own computer is automatically shared into the machine as /vagrant, and that is where you should put your work. Everything else inside the machine disappears the day you run vagrant destroy, and you will run that command, because that is how this tool is meant to be used.

Save your code in the shared folder, never in the home folder inside the machine. Then it stays on your real computer, and the machine becomes what it should be: a disposable thing.

Also worth knowing: for a few years now, Vagrant has been under a license called BSL. To learn, develop and run your own projects it is free, and that applies to one company. It is only when you build a competing service out of the tool itself that the terms kick in.