21 June 2014 Karim Elatov

In order for your Vagrant Box to support versioning, you have to use the vagrant cloud (create an account on https://vagrantcloud.com). From Creating A Base Box:

You can distribute the box file however you’d like. However, if you want to support versioning, putting multiple providers at a single URL, pushing updates, analytics, and more, we recommend you add the box to Vagrant Cloud.

You can upload both public and private boxes to this service.

Another note is that you have to use vagrant version 1.5 or above, from Box Versioning:

Since Vagrant 1.5, boxes support versioning. This allows the people who make boxes to push updates to the box, and the people who use the box have a simple workflow for checking for updates, updating their boxes, and seeing what has changed.

So login to the vagrantcloud site and click on “Create One”:


Fill out all the information (like name and description of box):


Give the Box a version and create a comment for the version:


Assign a provider to the box:


I created this one for VirtualBox. Then provide a URL of the box file, to upload to the vagrant cloud you need to have a paid account. I uploaded my vagrant box to my test google drive account:


After that you have to release that version of the vagrant box:


After it’s successful, you will see the successful page:


At this point you can add that box to your local vagrant instance like so:

[email protected]:~$vagrant box add elatov/opensuse13-32
==> box: Loading metadata for box 'elatov/opensuse13-32'
    box: URL: https://vagrantcloud.com/elatov/opensuse13-32
==> box: Adding box 'elatov/opensuse13-32' (v0.0.1) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box
==> box: Successfully added box 'elatov/opensuse13-32' (v0.0.1) for 'virtualbox'!

Now if I go back to vagrant cloud, I can add a new version. Fist click on your box in vagrant cloud:


Then click on “create a version +”:


Then name the version:


Then configure the provider for the new version:


The go ahead and release the new version:


If successful, you will see the following:


Now in your local vagrant instance you can check if any of your boxes are out of date:

[email protected]:~$vagrant box outdated --global
* 'opensuse13-32' wasn't added from a catalog, no version information
* 'hashicorp/precise32' (v1.0.0) is up to date
* 'elatov/opensuse13-32' is outdated! Current: 0.0.1. Latest: 0.0.2

We can see that the opensuse from the vagrant cloud is now outdated. To update the box to the latest version, you can run the following:

[email protected]:~$vagrant box update -b elatov/opensuse13-32
Checking for updates to 'elatov/opensuse13-32'
Latest installed version: 0.0.1
Version constraints: > 0.0.1
Provider: virtualbox
Updating `elatov/opensuse13-32` with provider 'virtualbox' from version
'0.0.1' to '0.0.2'...
Loading metadata for box 'https://vagrantcloud.com/elatov/opensuse13-32'
Adding box 'elatov/opensuse13-32' (v0.0.2) for provider: virtualbox
Downloading: https://vagrantcloud.com/elatov/opensuse13-32/version/2/provider/virtualbox.box
Successfully added box 'elatov/opensuse13-32' (v0.0.2) for 'virtualbox'!

It doesn’t actually check the versions of the file and it will download the box again, even if it’s the same (the download takes about 5mins, 700MB from gdrive… not bad). Here is a wget of the file:

[email protected]:~/test2$wget https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box
-2014-06-11 14:08:27--  https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box
Resolving vagrantcloud.com (vagrantcloud.com)...,
Connecting to vagrantcloud.com (vagrantcloud.com)||:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://googledrive.com/host/0B4vYKT_-8g4IdzQ0eHV5YWZtQU0/vagrant-opensuse13-32.box [following]
--2014-06-11 14:08:28--  https://googledrive.com/host/0B4vYKT_-8g4IdzQ0eHV5YWZtQU0/vagrant-opensuse13-32.box
Resolving googledrive.com (googledrive.com)...,,, ...
Connecting to googledrive.com (googledrive.com)||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 721075604 (688M) [application/x-gzip]
Saving to: ‘virtualbox.box’
100%[======================================>] 721,075,604 2.57MB/s   in 3m 15s

2014-06-11 14:11:43 (3.53 MB/s) - ‘virtualbox.box’ saved [721075604/721075604]

FINISHED --2014-06-11 14:11:43--
Total wall clock time: 3m 17s
Downloaded: 1 files, 688M in 3m 15s (3.53 MB/s)

At this point you will have two different versions of the vmdks as well:

[email protected]:~$tree .vagrant.d/boxes/elatov-VAGRANTSLASH-opensuse13-32/
├── 0.0.1
│   └── virtualbox
│       ├── Vagrantfile
│       ├── box-disk1.vmdk
│       ├── box.ovf
│       └── metadata.json
├── 0.0.2
│   └── virtualbox
│       ├── Vagrantfile
│       ├── box-disk1.vmdk
│       ├── box.ovf
│       └── metadata.json
└── metadata_url

4 directories, 9 files

And vagrant will list them as separate boxes:

[email protected]:~$vagrant box list
elatov/opensuse13-32 (virtualbox, 0.0.1)
elatov/opensuse13-32 (virtualbox, 0.0.2)
hashicorp/precise32  (virtualbox, 1.0.0)
opensuse13-32        (virtualbox, 0)

To remove the old version you can run the following (to save space on the local machine):

[email protected]:~$vagrant box remove elatov/opensuse13-32 --box-version 0.0.1
Removing box 'elatov/opensuse13-32' (v0.0.1) with provider 'virtualbox'...

If for whatever reason you wanted to download the old version you could do the following:

[email protected]:~$vagrant box add elatov/opensuse13-32 --box-version 0.0.1
==> box: Loading metadata for box 'elatov/opensuse13-32'
    box: URL: https://vagrantcloud.com/elatov/opensuse13-32
==> box: Adding box 'elatov/opensuse13-32' (v0.0.1) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box
==> box: Successfully added box 'elatov/opensuse13-32' (v0.0.1) for 'virtualbox'!

If you want to init an old box, you can specify the URL for the first version like so:

[email protected]:~/test2$vagrant init elatov/opensuse13-32 https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box
A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`vagrantup.com` for more information on using Vagrant.
[email protected]:~/test2$vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'elatov/opensuse13-32'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'elatov/opensuse13-32' is up to date...

You will notice the URL defined in the Vagrantfile of the old version and not in the new version:

[email protected]:~$grep box_url test1/Vagrantfile test2/Vagrantfile
test2/Vagrantfile:  config.vm.box_url = "https://vagrantcloud.com/elatov/opensuse13-32/version/1/provider/virtualbox.box"

Another note, if you don’t want to keep downloading the box file, you can repackage the downloaded box file and store it locally as well. This is accomplished with the following command:

[email protected]:~$vagrant box repackage elatov/opensuse13-32 virtualbox 0.0.2

then in the current directory you will have a package.box file:

[email protected]:~$ls -lh pack*
-rw-r--r--  1 elatov  staff   688M Jun 11 14:30 package.box

I also ran into a cool git hub project to host your own vagrant cloud: vagrant-catalog. As long as the server/location has a valid json it should allow versioning of the box as per this google forum.

blog comments powered by Disqus