Versioning your Vagrant box

Overview

After playing around with Vagrant versioning I decided to make this tutorial
for others doing this for the first time. The documentation on this feature and
how to use it is sparse and scattered. If you have any comments on improving
this please let me know.

Vagrant

Vagrant is a tool for building complete development environments. With an
easy-to-use workflow and focus on automation, Vagrant lowers development
environment setup time, increases development/production parity, and makes
the “works on my machine” excuse a relic of the past.

Vagrant Cloud

Vagrant Cloud is a place for sharing, discovering, and creating Vagrant
environments. Presently, Vagrant Could is in beta.

Using a custom or existing box

To follow this tutorial it is recommended to have a box. You may use an
existing box or create a custom box. Wheather you are creating or using an
existing box you don’t need to do anything special to the box to implement
versioning.

For the purpose of this tutorial I will use an existing box I have created
using Packer for Ubuntu. An example of the templates used can be
found in my GitHub project, skoblenick/packer-examples.

Adding a version to the Vagrantfile

Changes in Vagrant 1.5.0+ to the vagrant API have added the ability for
versioning. The two you mainly have to concern yourself with are:

config.vm.box_version

The version of the box to use. This version will need to match a ‘Released’
version on Vagrant Cloud

config.vm.box_check_update

If true, Vagrant will check for updates to the configured box on every
vagrant up

Running Vagrant at this point will fail. Vagrant will be unable to find
“skoblenick/precise64”, as a result you’ll get a 404 Not Found.

Box Namespaces

Prior to Vagrant 1.5.0 a box would have typically been referenced by a local
file path or a HTTP URL to the hosted box.

Vagrant 1.5.0 introduced namespaces which follow a pattern like
“<vagrantcloud_user>/<box_name>”. You can think of this as an
alias which Vagrant parses into a HTTP URL by querying Vagrant Cloud. This
doesn’t mean your box needs to be stored on Vagrant Cloud. In most cases all
that is store is the metadata that defined the box.

Creating an account on vagrantcloud.com

You will need to create an account on Vagrant Cloud. I won’t give a
step-by-step for this as the signup is pretty straight forward. Once your
account has been created and verified, login.

Defining a box on Vagrant Cloud

As Vagrant Cloud is in beta the steps described here may change in future. The
following steps will create a new box.

Select “Create Box” in the main navigation.

Populate the general information about your box.

In my case I will name by box “precise64”.

I am going to also make this box private as it will reside on my development web server.

Enter the name of your provider. In my case I have VMware Fusion so I will enter “vmware_desktop”.

Click the “URL” button.
The URL button will reveal an input for the box URL and a button to add the provider.

Enter the URL to your box. In my case I will enter http://localhost/boxes/precise64-1.0.0_vmware.box.

Click the “Create provider” button.

You will be prompted to edit the version. If you feel the need to update what you enter you can. The important part of this screen is the green “Release now” button.

Click the “Release now” button. This will not make the box public but will set it’s status to active. This will allow users we add to the collaborators to start using the box. As the creator of the box we don’t need to add ourselves to the collaborators.

Before we can go downloading the box, remember I made my box private. With this
setting there is an extra step. Vagrant must know which user to login to
Vagrant Cloud with.

vagrant login

Creating a public box doesn’t require this step. However if you’ve created a
private box as we have above you will need to run the following command in
Terminal where you be running Vagrant.

username$ vagrant login
In a moment we'll ask for your username and password to Vagrant Cloud.
After authenticating, we will store an access token locally. Your
login details will be transmitted over a secure connection, and are
never stored on disk locally.
If you don't have a Vagrant Cloud account, sign up at vagrantcloud.com
Username or Email: user@example.com
Password (will be hidden):
You're now logged in!

vagrant up

Finally we can vagrant up in Terminal and our box will be downloaded, cloned,
and spawned. Alternatively we may just add the box with
vagrant box add skoblenick/precise64.