Starting A Vagrant Ops Sandbox

Here’s how you can set up and get going with Vagrant! Using this overview, you will have a usable virtual machine going really fast.

1. Install Vagrant.

To get started, you’ll need to install Vagrant on your local development machine. Go to Vagrant’s download page and install the most recent version from there.

Note: if you’re on Ubuntu or Debian, you can also follow the steps under Linux -> Ubuntu/Debian to add the apt repository and stay updated.

“Why not use the package manager version” you may ask? You could, but for example the Ubuntu one is known to be notoriously outdated. This sometimes leads to bugs and unexpected behaviour. I find it easier to roll with the versions from the site for this reason.

Once you’ve installed it, you can jump into your command line and check the version:

$ vagrant --version

2. Install VirtualBox

Vagrant is a tool to create and manage environments which run in in VMs. VirtualBox is a great free virtualization product. The way how you’re supposed to install it depends on your OS. Make sure to set it up well.

Note: once again, for instructions on adding an apt repository, see this page.

Attention! You might need to make sure that VirtualBox is actually ready to run, and running. Here’s a command which helped me make progress on Ubuntu:

/sbin/vboxconfig

I admit, it looked a bit more scary and complicated than I’m comfortable to admit here. Make sure you’re careful with this process!

3. Get a Vagrant Box

Vagrant boxes are basically VM images, which you use to create a new virtual machine. I like to use Ubuntu, as it is easy to handle, and offers mix of stable & reasonably recent packages. The current LTS (long time support) version is Ubuntu 21.04 LTS.

Note: this can change in the future :)

With Vagrant, you can get Ubuntu boxes from different providers.

Check out the search page for more OS choices.

The Vagrant docs recommend to stick to Ubuntu boxes from either bento or hashicorp themselves. (Read here for more details). The boxes from the canonical namespace are not recommended as they are known to cause issues.

“These are the only two officially-recommended box sets.”

While Hashicorp’s box is described as “minimal, highly optimized, small in size”, while the bento box is recommended “for other users”. From the box site, both seem to be around 500 MB large. I went with the bento version out of habit - they haven’t had any issues with them in the past.

You can add a box (downloading it to your machine) with the following command:

$ vagrant box add bento/ubuntu-21.04

# Note: choose option 2 for virtualbox

4. Start a Vagrantfile

Now you have everything ready to create a Vagrantfile.

Go into the folder where you want your deployment code to live (for example, the repository root of your Django app), and execute the following command:

$ vagrant init bento/ubuntu-21.04

# you could also specify a particular version:
# --box-version THE_NAME_OF_THE_VERSION

This will create a well-documented Vagrantfile for you, which you can build on.

Here is my usual, modified, version of that initial file:

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

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-21.04"

  # Create a forwarded port mapping which allows access to a specific port
  # within the machine from a port on the host machine and only allow access
  # via 127.0.0.1 to disable public access
  config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1"
  config.vm.network "forwarded_port", guest: 8000, host: 8081, host_ip: "127.0.0.1"

  # Changing the synced folder could mess with stuff like local ansible provisioning eventually :(
  # You can enable it though!
  #config.vm.synced_folder ".", "/home/vagrant/code"

  config.vm.provider "virtualbox" do |vb|
    # Don't display the VirtualBox GUI when booting the machine
    vb.gui = false

    # Customize the amount of memory on the VM:
    vb.memory = "2048"
  end
end

The Vagrantfile is a modified version of the one you get with vagrant init:

• Enable “headless mode” so no window pops up where the VM is running.
• Set a memory limit for the VM to 2 GB.
• Forward port 80 of the VM to 127.0.0.1:8080 and port 8000 to 127.0.0.1:8081 on the host.

Now we are ready to start a brand-new Ubuntu VM based on those configs.

Note: If you want to see the excellent default template, with many helpful comments, run vagrant init in a temporary directory and look at the output. Lots of good stuff there!

5. Vagrant Up!

With all of the preparations in place, creating a new VM is as easy as typing:

$ vagrant up

Once it has started, and you make changes to your Vagrantfile, you’ll need to run

$ vagrant reload

for the changes to take effect.

Now you can SSH into your box.

6. SSH Into Your VM

Once your Vagrant VM is up, you can connect to it directly via the commandline:

$ vagrant ssh

Congratulations! You’re in your brand-new Vagrant environment.

Your project’s code (shared from the local machine) can be found in the directory

/vagrant in the new VM. Check out the content:

$ cd /vagrant
$ ls

As it’s a shared folder, you should be aware that any file you delete or change here, will be deleted or changed on your development machine as well. Take care, and make sure to have your code under version control, so you could recover from things going wrong.

The upside of a shared folder is: you can edit code as usually on your machine, and your VM will get the newest changes right away.

Eventually: Total Destruction

Once you feel that you are ready to try a more automated, or more elaborate way to deploy your application, you can get rid of the complete Vagrant VM, and start from scratch. This is a good thing! You’ll have a fresh OS, which is in a blank state. This will help you to make sure that your processes are complete and reproducible.

Destroying the environment and starting from scratch is as easy as typing the following two commands:

$ vagrant destroy
$ vagrant up

Now, Vagrant will create a fresh VM. I hope your notes from the last time around are good, and you’ll get your environment up even faster!

Note: currently writing an article on using Ansible to provision the machine TODO publish and link it