Installation

Getting the VM

Getting the local VM is a two-step process. First, download (or install via your OS’s package management system) the VirtualBox application. This is a great piece of software that will let you run the SeqWare Ubuntu VM on whatever OS you currently have.

• Oracle Virtual Box

Next, you will need to download our current VM image which is linked below. Please make sure you are using the latest version, when we post a new one we will tweet about it so consider following us on Twitter.

• SeqWare_1.1.0.ova
• SeqWare-1.0.13.ova (this is the VM we recommend for the ICGC PanCancer project for data train 2.0)

If you run into issues downloading the VM, please try wget and use md5sum to verify your download. For example:

$ wget https://s3.amazonaws.com/oicr.vm/public/seqware_1.1.0-beta.0.ova
--2015-01-23 11:40:31--  https://s3.amazonaws.com/oicr.vm/public/seqware_1.1.0-beta.0.ova
Resolving s3.amazonaws.com (s3.amazonaws.com)... 54.231.17.200
Connecting to s3.amazonaws.com (s3.amazonaws.com)|54.231.17.200|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 2644320768 (2.5G) [application/octet-stream]
Saving to: `seqware_1.1.0-beta.0.ova'

100%[==========================================================================================>] 2,644,320,768     15.6M/s   in 3m 26s  

2015-01-23 11:44:01 (12.2 MB/s) - `seqware_1.1.0-beta.0.ova' saved [2644320768/2644320768]

$ md5sum seqware_1.1.0-beta.0.ova 
107b75726de602750e1f82f84f0b20f5  seqware_1.1.0-beta.0.ova

Open VirtualBox and use the “Import Appliance” tool to create a new SeqWare VM on your system. Make sure you set the memory to the max you can afford, I recommend at least 12GB of memory for the VM. You can then launch it and you will be presented with a fairly standard Linux desktop with links to the project documentation to give you an idea of where to begin (the “Getting Started” guide here provides a walk-through of using this VM).

Note: When you import the VM ensure that “Reinitialize the MAC address of all network cards” is NOT checked. (Why?)

Note: When you import the VM you need to set your memory and CPU correctly. Do not over-commit resources (especially memory) since that will cause the machine to “swap” memory to disk and slow your computer to a crawl. This VM is intended for you to see SeqWare in action and then create your own workflows. If you are making a workflow that will take 16GB of memory then you will need a VM running on a machine that can afford to give 16GB of memory to VirtualBox. Also, we only distribute 64-bit VMs which all modern PCs will support and VirtualBox makes use of various virtualization extensions which most modern PCs support (but you may want to check with your computer vendor).

Logging In

The login username is vagrant and the password is vagrant. If you need to become root use sudo bash. You will initially login as the vagrant user and will then switch to the seqware user which has been setup with our utilities.

By default the VM will open port 2222 for ssh. You can connect to the running VM from an external console using the following command:

sshpass -p 'vagrant' ssh -p 2222 vagrant@localhost
sudo -u seqware -i

Note: Obviously, you will not want to run this VM anywhere that is network-accessible. If you do, make sure to disable the above login and use SSH keys.

What Can You Do With It?

As the note above mentioned, you can use this VM to see what each of the SeqWare tools can do, kick the tires, explore the docs more, etc. If you decide to use SeqWare then this VM can also be your development and testing environment for workflows. Once you have created and tested a given workflow, you can also use the SeqWare commands on this machine to “install” the workflow bundle into a production system. Or you can even hook up this VM to a real local grid environment (such as an SGE cluster) for running workflows. This is exactly what we did at OICR, our SeqWare hosts are all virtual machines that can submit workflow jobs to our physical cluster. You can find more information on this in the “SeqWare Pipeline” section of our documentation.

Getting an Amazon Cloud Account

To use Amazon’s cloud (also know as Amazon Web Services or AWS) you need to sign up for an account and that requires a credit card. Also, while launching these instances is simply point and click using Amazon’s very nice AWS console, actually using these machines requires the same level of experience as using the local VM above. If you are looking for a completely graphical, web-based service you should consider using one of the cloud-based providers like Nimbus Informatics or DNAnexus.

Signup for the Amazon cloud here

Running the VM

What makes AWS EC2 so amazingly awesome is its excellent support for both graphical UIs and programmatic APIs for controlling the cloud. It is your choice on how you want to launch the VM, either through the console or via one of the many command line and programmatic tools available. The details are subject to change so we refer to Amazon’s thorough documentation. Specifically this guide should be very helpful in learning how to use Linux VMs on Amazon’s cloud.

Logging In

There is no graphical desktop to log into. Instead you will need to follow the directions on the Amazon site for using ssh to log into your running VM. There you will have a command line interface to interact with the SeqWare tools. You can also view the SeqWare Portal and SeqWare Web Service remotely in your browser if you have previously opened the ports 22, 8080, and 80.

Specifically, follow this Amazon guide for logging into your SeqWare instance using ssh.

You will want to login as the “ubuntu” user, use “sudo umount /mnt” to disable any ephemeral drives, and then use “sudo -u seqware -i” to become the SeqWare user and walk through the steps of the tutorials. dd

What Can You Do With It?

You can launch this public AMI which will give you a server with all the SeqWare projects pre-configured and loaded with some small examples. You can then use the running VM to test workflows and write your own. Since this VM runs on the fairly powerful HPC node type, you can actually use it to get real work done. This instance is powerful enough to analyze a whole human exome in 4-8 hours and you can, of course, launch many instances simultaneously to process multiple exomes in parallel. Future releases of SeqWare will include scripts to setup clusters of HPC nodes that will allow you to process whole human genomes. In the mean time we recommend investigating the excellent StarCluster cluster launching tool.

Note:Keep in mind Amazon charges approximately $1.30 USD per hour to run these instances, it is your responsibility to monitor your cloud usage and turn your VMs off when not in use! You will be billed for each hour (rounded up).