# Running HippUnfold with a Vagrant VM

This option uses Vagrant to create a virtual machine that has Linux
and Singularity installed. This allows you to use Singularity to run HippUnfold 
from a clean environment, whether you are running Linux, Mac or Windows (since all
three are supported by Vagrant). Note: VirtualBox does the actual 
virtualization in this example, but Vagrant provides an easy and reproducible way to create and 
connect to the VMs (as shown below).


## Install VirtualBox and Vagrant

The example below uses Vagrant and VirtualBox installed on Ubuntu 20.04. 

The [Vagrant install instructions](https://developer.hashicorp.com/vagrant/downloads) describe
what you need to do to install on Mac, Windows or Linux.

Vagrant must use a **provider** for the actual virtualization. The instructions here assume you
are using VirtualBox for this, since it is free and easy to use, but in principle should work with any
virtualization provider.  The [VirtualBox downloads page](https://www.virtualbox.org/wiki/Downloads) 
can guide you through the process of installing it on your system (Mac, Windows, Linux supported).


## Create a Vagrant Box 

Once you have Vagrant and VirtualBox installed, the following screencast demonstrates 
how you can setup a Box with Singularity pre-loaded on it. The main steps are to 1) create a Vagrantfile, 2) start the box using `vagrant up`, and 3) connect to it using `vagrant ssh`.

Note: These screencasts are more than just videos, they are asciinema recordings -- you can pause them and then copy-paste text
directly from the asciinema cast!

```{asciinema} ../casts/vagrant_hippunfold_setup.cast
---
preload: 1
speed: 2
---
```

This is the `Vagrantfile` used in the video, for quick reference:
```
Vagrant.configure("2") do |config|
  config.vm.box = "sylabs/singularity-3.7-ubuntu-bionic64"
  config.vm.provider "virtualbox" do |vb|
     vb.cpus = 8
     vb.memory = "8096"
   end
end
```


## Download the test dataset

We are downloading the test dataset with the following 
command:
```
wget https://www.dropbox.com/s/mdbmpmmq6fi8sk0/hippunfold_test_data.tar
```


```{asciinema} ../casts/vagrant_hippunfold_get_data.cast
---
preload: 1
speed: 2
---
```


## Download the HippUnfold container

We pull/build the container from DockerHub:
```
singularity pull docker://khanlab/hippunfold:latest
```

## Run HippUnfold
This demonstrates the basic HippUnfold options, and how
to perform a dry-run:

```{asciinema} ../casts/vagrant_hippunfold_dryrun.cast
---
preload: 1
speed: 2
---
```

Finally, we can run HippUnfold using all the cores:

```{asciinema} ../casts/vagrant_hippunfold_run.cast
---
preload: 1
speed: 2
---
```