Skip to content

Running on a PC (Windows) with Vagrant

Jump to bottom
Chris Jackson edited this page Nov 28, 2022 · 11 revisions

NOTE: the following was tested with:

  • Windows version 10.0.19041 Build 19041
  • VirtualBox version 6.1.8
  • Vagrant version 2.2.14
  • ssh installed (at a command prompt, the command where ssh returns the installation path C:\Windows\System32\OpenSSH\ssh.exe on my machine)

To run the pipeline on a PC (Windows), you can use a virtual machine running Linux Ubuntu. You can get this up and running in about 15 minutes. The general installation process is as follows.

  1. Install VirtualBox for Windows. This is just a standard Windows click-through install.

  2. Install Vagrant for Windows. This is just a standard Windows click-through install.

  3. Install a plugin for resizing the hard disk size of Vagrant machines. At a Windows command prompt, type command vagrant plugin install vagrant-disksize, followed by enter

  4. OPTIONAL: install Vagrant Manager for Windows. This program provides a handy GUI for managing Vagrant machines e.g. viewing those currently running, starting and stopping them, etc. This is just a standard Windows click-through install.

  5. Create a directory to be used for your Vagrant virtual machine e.g. open a Windows Command Prompt, change to the Desktop directory (or wherever you'd like to create a new directory) and type mkdir hybpiper-vagrant-vm & cd hybpiper-vagrant-vm.

  6. Copy the provided Vagrant file into the directory you’ve created. The Vagrant file can be obtained by downloading this repo from the main page; the required file is simply called Vagrantfile. Alternatively, you can copy the content here to a text file, and save it as Vagrantfile (note the lack of file extension).

  7. Open Vagrantfile in a text editor, and change the line vb.memory = "5120" and vb.cpus = "4" to match the amount of RAM (here 5120 MB or 5GB) and the number of CPUs you’d like your virtual machine to have. You’ll probably want to use fewer CPUs and less RAM than available on your host machine, so that there are sufficient resources to still run Windows without bogging down. Save the file.

  8. By default, the HDD drive size for the Vagrant machine is set to ~20 GB. If you need more for your analysis this can be expanded. In the Vagrantfile, change the line config.disksize.size = '20GB' to the larger size required (e.g. ‘30GB'). Save the file.

  9. In the directory containing Vagrantfile, type the command vagrant up and press enter. The first time you run this command it’ll download the appropriate Vagrant “box” containing Ubuntu 18.04 with Singularity installed. It’ll then install Nextflow, and launch the virtual machine.

  10. Connect to the virtual machine using the command vagrant ssh.

  11. By default, the directory (eg. hybpiper-vagrant-vm) containing the Vagrantfile in your host OS (Windows) will be mounted inside the Vagrant machine at the path /vagrant/. So, you can create a subfolder within the directory hybpiper-vagrant-vm called data via Windows Explorer, and just drag-and-drop data (e.g. read-file folders and target files) into hybpiper-vagrant-vm/data. These will then be available in the Vagrant machine at /vagrant/data/.

  12. The pipeline script hybpiper.nf and its config file hybpiper.config will already be in the /home/vagrant/bin/hybpiper-nf/ directory within the Vagrant machine. So you can now run the HybPiper pipeline! For example (depending on which folders you’ve copied your data to), you might use a command like:

    nextflow run ~/bin/hybpiper-nf/hybpiper.nf -c ~/bin/hybpiper-nf/hybpiper.config --illumina_reads_directory /vagrant/data/reads_for_hybpiper/ --target_file /vagrant/data/Angiosperms353_targetSequences.fasta

NOTES:

  • The same details regarding download of the Singularity container in Linux apply here i.e. if you don’t change the Nextflow config file, Nextflow will do it for you automatically the first time you run the script. Or, you could download it manually and change the config file to point towards the full path of the image.

  • You’re free to install any other programs you want in the Vagrant machine as well. By default (i.e. specified in the Vagrantfile) I’ve installed curl, the text editor vim, as well as the terminal manager screen.

  • Once you’re done, you can view your results via command line within the Vagrant machine, or you can copy them across to the /vagrant/data folder so that they’re accessible via Windows/Explorer.

  • When done, you can exit your SSH session with the Vagrant machine using the command exit. Note that it will still be running in background, so if you want to shut it down (you won’t lose your data - it’s persistent on the Vagrant machine HDD), use the command vagrant halt. You can also use Vagrant Manager (if installed) to perform these sorts of tasks using a nice simple GUI.

  • To restart the Vagrant machine, just move to the directory with the Vagrantfile and type vagrant up then vagrant ssh again. This will be much faster the second time round, as all downloads and installations have already been completed.

  • If you want to delete the Vagrant machine (and all the data it contains), use the command vagrant destroy, and follow the prompt. You can then simply generate a fresh machine using the vagrant up command.

Let me know if you run into any problems - I’m happy to help troubleshoot them with you!

Clone this wiki locally