Using VirtualBox and Vagrant to Host CollectionSpace

VirtualBox and Vagrant can make it easier and faster to develop for, test, and evaluate CollectionSpace deployments.

In combination, these tools allow you (for example) to create 'virtual' Linux hosts on which you can readily bring up CollectionSpace servers, modify and test them, and even throw them away when done, knowing that you can quickly and easily bring up new ones.

Here's a quick start guide for using these tools, with the example of setting up a virtual machine (VM) for a host running Fedora Linux version 18. The following set of commands is literally all that's required to get this host up and running. (And you can get a host running other Linux distributions, such as Ubuntu, Debian, or CentOS, in exactly the same way, just by changing a single URL):

Install the VirtualBox and Vagrant applications

The following only needs to be done once:

Install Vagrant, via the Vagrant Downloads page

Install Oracle's VirtualBox application, via the VirtualBox Downloads page

Set up a virtual machine ('box'), to be managed by Vagrant

The following commands only need to be entered once, for each virtual machine you set up:

Use Vagrant to download a pre-existing VirtualBox virtual machine (aka 'VM' or 'box') from a trusted source, such as a Linux distribution's website, and add it as a box that Vagrant can manage. The following example demonstrates how to use Vagrant to download a Fedora 18 (64-bit) VM from the Puppet Labs website, and add it to Vagrant's management using the (arbitrarily named) fedora18 alias.
```
vagrant box add fedora18 \
http://puppet-vagrant-boxes.puppetlabs.com/fedora-18-x64-vbox4210-nocm.box
```

There are many VirtualBox VMs from various sources available for download from sites such as http://www.vagrantbox.es and others. Some of these are official (e.g. from Ubuntu - see the boxes available for download from http://cloud-images.ubuntu.com) or otherwise trusted (e.g. from the Vagrant website itself at http://files.vagrantup.com or Puppet Labs at http://puppet-vagrant-boxes.puppetlabs.com), while others are clearly unofficial and hence less trusted.

As an alternative, you can download an official ISO disk image of a Linux distribution, then add it to VirtualBox and then Vagrant. The instructions for doing so can be added here later as needed.

Create a directory (with any name) to hold the Vagrant project corresponding to your VM 'box'; e.g.
```
mkdir fedora18vm
```

Change to that directory
```
cd fedora18vm
```

Set up the current directory as a Vagrant project, to work with that VM 'box' (a one-time command):
```
vagrant init fedora18
```

This will create a file named Vagrantfile within that directory, which contains configuration settings for your project.

Start, stop and explore your virtual machine

The following commands can be entered repeatedly. All of these commands may need to be run from within the project directory:

Boot up that VM:
```
vagrant up
```

Connect via ssh into that VM's operating system (no password required), as the user vagrant, which has sudo privileges:
```
vagrant ssh
```

Suspend that VM (much like sleep/hibernation mode) ...
```
vagrant suspend
```

... or gracefully shut down that VM:
```
vagrant halt
```

Taking snapshots and rolling back to them

If you wish, you can also take a snapshot of the state of the virtual machine at any point and later roll back to it:

Install a Vagrant snapshot plugin (a one-time command):
```
vagrant plugin install vagrant-vbox-snapshot
```

Then, at any time:

Take a snapshot

vagrant snapshot take my_snapshot_name_goes_here

Do some work ... then decide to roll back, perhaps to repeat the work with some variation, to try out some new code, or to resolve a problem state:

Roll back the VM's state to the last snapshot taken:
```
vagrant snapshot back
```

List available snapshots:
```
vagrant snapshot list
```

Roll back to a named snapshot:

vagrant snapshot go my_snapshot_name_goes_here

Configuring a virtual machine

By editing the Vagrantfile file in your Vagrant project directory for a particular VM, you can change networking access to the virtual machine, and otherwise configure it in all sorts of useful ways.

Making your configuration changes take effect requires editing the file - its extensive comments can help guide you - then entering either a vagrant reload command, or a vagrant halt (if needed) and vagrant up command.

Automating virtual machine setup

You can also set up scripts that can be run on the VM on a first-time or subsequent startup, on demand, or during a restart. (This ability is often referred to as "provisioning," as it can used to automate the creation of a specified environment.) For some notes on this, see comments on CSPACE-6283.