Customising a Vagrant box with Veewee

In my job I’ve noticed that the number of web sites, applications and APIs keep growing and all need servers to run on. I’m not a Systems Administrator but being a lone developer I want to try and keep as much of my time focused on doing what I love, building great apps for people. To help combat the issue of managing multiple servers I started to experiment with Chef and I have to say, after a bit of a learning curve, I like it, or I like what it enables me to be getting on with.

Recently, I’ve been tasked with working alongside another developer and the topic of a development environment came up when working on an existing site. Until now I had my VM running on my laptop mirroring production as best as possible and I was happy but someone else now needed the same environment I had. In fact, my local development environment was more akin to a shared hosting platform. That is, I’m running multiple sites on my VM, simply because it was easier than launching a whole new VM and configuring it for each site. I didn’t want to give this guy a copy of my current VM since it would have all of my settings running on it and after playing with Chef for a bit, I came across Vagrant and knew that it supported provisioning with Chef and allows developers to share VMs. I also thought that I could now have a VM dedicated per website. With this in mind I got to work.

I quickly managed to get a new VM provisioned and configured against a base role in Chef but noticed that the default locale settings applied were US centric, however I needed the UK locale set. I thought about doing this via Chef initially but Googled around and came across Veewee. Veewee allows you to configure your own base boxes for import into Vagrant straight from the ISO and this was exactly what I needed. Also, it adds some comfort knowing that I know what the ingredients are in configuring and building your own base box as opposed to simply trusting the default Vagrant Lucid32 box.

How I built my base box

To configure my base box, I first started out by updating to the latest versions of VirtualBox and Vagrant. At the time of this blog post that was 4.1.10 and 1.0.1 respectively.

Next, I needed to actually install Veewee on my host machine, to do this I ran:

 gem install veewee

Once completed, this gave me a new command available in Vagrant called basebox. The first sub-command I needed to use was called templates. I ran:

 vagrant basebox templates

This displayed a list of the currently available OS templates for configuring an ISO image. When I ran this list they were missing the Ubuntu Server 10.04.4 32bit template which was what I was looking for. At the time I figured I would take the 10.04.3 template and either hack the config files or upgrade it once the OS had installed. It turned out I could do the former. So I chose my template:

 vagrant basebox define 'ubuntu-10.04.3' 'ubuntu-10.04.3-server-i386' 

This created the following directory structure:

└── definitions
   └── ubuntu-10.04.3
       ├── definition.rb
       └── preseed.cfg

For the ubuntu definition, three files were created to control the configuration of a new VM.

The definition.rb file has settings needed for provisioning a VM under VirtualBox, settings to the ISO image used to build upon and the OS boot settings themselves. In this file I changed the relevant locale settings in the :boot_cmd_sequence to reflect the UK values needed. Also, I changed the ISO details to use the 10.04.4 release of Ubuntu. Finally, I changed the directory name of the definition to ‘ubuntu-10.04.4’.

The preseed.cfg file contains OS install settings, again I changed some values here to reflect the UK locale.

The postinstall.cfg file contains post-OS-install commands. This is mainly the required dependencies that Vagrant needs to configure an OS with Chef and Puppet. From this file, knowing that I’m only using Chef, I stripped out the Puppet install commands. Also, I noticed that the Ruby install version was stuck on 1.8.7 because Puppet doesn’t support the 1.9 release, so I changed the settings to point to the latest release and did the same for Ruby Gems. Finally, I added some install steps for a dependency Ruby Gems has which is a YAML parser (

With these files hacked to my needs, I proceeded to build the VM running:

 vagrant basebox build 'ubuntu-10.04.4'

If the ISO image is not found in ./iso then Veewee will prompt, asking for confirmation to download the ISO. After accepting, take a Coffee break as now it will download the ISO, install it and then pre-configure it to work with Vagrant. During install, every step can be seen on screen. Pages worth. Especially Ruby.

Once this was complete, I validated the build by running:

 vagrant basebox validate 'ubuntu-10.04.4'

All tests passed except for one. However, this was just confirming that Puppet wasn’t installed on the system. If you need to you can connect to this new VM by running:

 ssh -p 7222 vagrant@

Assuming you didn’t customise the default SSH port. The default username and password are set as vagrant. Once logged in, you can do any manual validation checking to ensure the build ran smoothly. Also, to keep the size of the base box to a minimum you can clear the cache on the system by running:

 apt-get clean

The final step with Veewee was to package up the VM as a Vagrant box. To do this I simply ran:

 vagrant basebox export 'ubuntu-10.04.4'

This simply shutdown the VM that was already running and created the box in the current directory. This may take a minute. This finally gave me a directory structure of:

├── definitions
│   └── ubuntu-10.04.4
│       ├── definition.rb
│       ├──
│       └── preseed.cfg
├── iso
│   └── ubuntu-10.04.4-server-i386.iso

That’s it. After adding this box to Vagrant and applying my base Chef role, all of the locale settings I needed were set. The one thing I did notice after all of this, was that the VM it created remained in the VirtualBox GUI named after the Veewee definition should you wish to remove it.

One other thing of note here is that the Vagrant box created is tied to the version of VirtualBox in use due to the GuestAdditions package installed on the guest VM created. That means when distributing this box the recipient needs this version of VirtualBox running. Of course, if you keep your Veewee definitions in version control you can always update the box as necessary.

This was actually a lot simpler than I thought it was going to be. In all, I think it only took me less than two hours excluding the OS download, install and configure step. Should you want to the Veewee definitions they can be found in full on GitHub at

2 Comments Customising a Vagrant box with Veewee

  1. yggdrasil

    Thanks for the clear explanation. Going through this process myself, and the writeup definitely helped.

    I would request to also install the Puppet package. That way these instructions and the resulting Box is useful to the entire Vagrant community, since Vagrant supports Chef and Puppet. An added bonus is that all the ‘vagrant validate’ tests will pass.

  2. James Cuzella

    Excellent writeup on veewee! This greatly helps to get a quick overview of the veewee box build process, templates, and definitions directory structure. It looks like the veewee documentation is incorrect about the ‘export’ command.

    The one you posted (`vagrant basebox export`) is correct. It looks like Vagrant uses veewee behind the scenes for most of the ‘basebox’ commands. However for ‘export’, vagrant is needed. Essentially this boils down to this command: `vagrant package ‘ubuntu-10.04.4’ –base ‘ubuntu-10.04.4’ –output`

    I really wish I had known about Vagrant and veewee at my last job (I had built some VBoxManage wrappers myself).


Leave a Reply

Your email address will not be published. Required fields are marked *