Installation instructions

hettling edited this page Jan 7, 2016 · 9 revisions

The SUPERSMART virtual research environment

The SUPERSMART pipeline requires many different software and analysis tools, of which some of them are not trivial to install. Therefore, SUPERSMART and all its dependencies can be installed automatically as a virtual research environment, downloadable as a virtual machine. One can think of a virtual machine as a guest computer with its own operating system, which is running on and is accessible from your host computer. This ensures that SUPERSMART always runs under similar conditions, regardless of the operating system (e.g. Windows, Linux, MacOS) you are running the guest on.

To run SUPERSMART on its virtual machine, two prerequisites are necessary:

Once you have installed the newest versions of VirtualBox and Vagrant, you can proceed to install the ready-made virtual machine.

Installing and running the SUPERSMART virtual machine

First of all, you will have to open a command-line window. This program to open is called Command Prompt or PowerShell on Windows and Terminal on Mac OS X. Linux users should be familiar with the command-line. We will now create a directory (folder) in which the virtual machine will be installed by typing the command:

$ mkdir my-supersmart

which creates a directory named my-supersmart. The name of the directory does not matter, you can give it any name you want (Note that special characters and spaces in directory names can cause trouble, however). We will then change into the newly created directory:

$ cd my-supersmart

and subsequently issue the command

$ vagrant init Naturalis/supersmart

which will place a file named Vagrantfile, into the directory. The Vagrantfile holds miscellaneous information about the virtual machine to be downloaded. We can check if the file is present by looking at the contents of our directory:

$ ls
## Vagrantfile

(Note that in Window's Command Prompt, the command is dir instead of ls). Now we are ready to download and eventually install the virtual machine, which is accomplished by one single command:

$ vagrant up 

Depending on your internet connection, this might take a while since a file larger than 10 GB will be downloaded.

If the vagrant up command finished without errors, you are ready to log on to the virtual machine:

$ vagrant ssh 

Logging onto the virtual host, you will see a different command prompt, giving the current version of SUPERSMART:

SUPERSMART v0.1.22 - 2f48494721 ~ $

Now, the pipeline commands smrt, smrt-utils and smrt-config are available. We describe in detail how to use these commands in an analysis-run-through and with an example.

Logging into the guest machine on WINDOWS

Please note that an ssh client is not installed by default on Windows systems. In order to log on to the virtual Linux guest machine, you need to download and run an ssh client, e.g. 'putty'; you will find a download link at http://www.putty.org/ . Putty does not require any installation steps, you can just double click on the downloaded file and a dialog window will open asking you for the connection details. In the field 'Hostname (or IP address)', enter: 127.0.0.1 In the field "Port", enter: 2222 and press 'Open'. A command prompt will open and ask you for a user name and password. For both, username and password, enter 'vagrant' to log in.