↓Skip to main content

Versioning your Vagrant box

Table of Contents

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:

  1. config.vm.box_version

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

  2. config.vm.box_check_update

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

Within your Vagrantfile you will have something similar too:

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

Vagrant.require_version ">= 1.5.2"

Vagrant.configure("2") do |config|
  config.vm.box = "skoblenick/precise64"
  config.vm.box_version = "1.0.0"
  config.vm.box_check_update = true

  config.vm.provider "vmware_fusion" do |v, override|
    v.gui = false
  end

end

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.

  1. Select “Create Box” in the main navigation.

  2. 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.
    • Fill in any additional information you feel necessary.
    • Click the “Create box” button.

  3. The next step is to define the version of your box.

    • Vagrant recommend using Semantic Versioning. So populate a version number for your box.
    • Populate a description if you feel so incline.
    • Click the “Create version” button.

  4. Next we want to add providers supported by the box we are defining

    • Click the “Create new provider” button.
    • 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.

  5. 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.