BugBuilder Virtual Machine

BugBuilder is available as a virtual machine image to allow access to the pipeline without the need to install the prerequisite packages and install and configure BugBuilder itself. In order to install the virtual machine you will need:

Installation Instructions

1. Install VirtualBox

Install VirtualBox (available from https://www.virtualbox.org), following the instructions on the VirtualBox website for your operating system.

2. Download BugBuilder VM

Download the BugBuilder virtual machine image, and save the image to a convenient location on your computer. The initial download will be around 16Gb, however the disk image will automatically expand in use up to a maximum of 100Gb, so ensure there is ample free space available to cope with the full 100Gb image.

3. Start VirtualBox

Start VirtualBox on your machine - how to do this will vary according to your operating system - typically there will be a VirtualBox icon installed in your start/applications menu. Once running you should see a window displayed such as that on the right.

4. Create virtual machine

It is now necessary to create a new virtual machine configuration on your computer, which will use the downloaded BugBuilder disk image. Click the ’New’ icon on the toolbar to open a dialog box for creating a new virtual machine. Enter ’BugBuilder’ in the ’Name’ field, then select ’Linux’ from the ’Type’ drop-down menu, and ’Red Hat (64-bit)’ from the ’Version’ menu. The window should look like the image alongside. Click the ’Next’ button.

5. Define virtual machine memory size

The next window displayed allows the amount of memory available to the virtual machine to be defined. Adjust the slider to set the desired amount of memory as shown on the righ. BugBuilder has been tested with 4Gb (4096 Mb) RAM allocated to the virtual machine, which appears to be sufficient for most Illumina assemblies, however PacBio and 454 data typically requires 6Gb-8Gb . Allocating larger amounts of memory to the virtual machine will result in improved performance, however it is necessary to ensure that the selected value leaves sufficient memory for other programs running on the computer. Typically you would not want to allocate more than half your systems memory to the BugBuilder virtual machine.

6. Select the BugBuilder disk image

Next, the hard-disk to be used by the virtual machine needs to be configured. Select the ’Use an existing virtual hard disk file’ option, then click the file icon alongside the dropdown menu and navigate to the BugBuilder.vdi file you downloaded in step 2. The window should look like that shown on the right. Now click the ’Create’ button.

7. Network configuration

Network Configuration: VirtualBox supports a number of different network modes. The network mode can be chosen by selecting the BugBuilder virtual machine in the VirtualBox window, , clicking the ’Settings’ button on the toolbar then ’Network’ in the left-hand pane of the window. The networking mode can then be selected in the ’Attached to:’ dropdown menu.

The default NAT (Network Address Translation) mode will allow the BugBuilder virtual machine to connect to other machines on the internet i.e. to download data onto the virtual machine, however it does not allow you to login to the virtual machine remotely (i.e. using SSH). If you require full network access for the virtual machine, then it will be necessary to use one of the alternate network modes. If your network provides a DHCP server, then ’bridged networking’ (which allows the virtual machine access to the network just like a physical machine) is probably the best configuration to use, although this depends upon your network configuration. Please contact your local network administrator to determine the most appropriate way to configure networking on your virtual machine. If you are not sure how to configure this setting, leave it set to 'NAT'.

Virtual Machine Usage

1. Starting the virtual machine

Once the virtual machine has been installed and configured, starting it is just a case of selecting the 'BugBuilder' virtual machine you installed in the left hand pane of the 'VirtualBox Manager' window, then clicking the 'Start' icon on the toolbar.

The virtual machine will then start up in a new window, and boot like a normal computer, with the screen displayed within a separate window. The initial screen displayed is the GRUB boot menu, which will then automatically boot the selected system after a 5-second delay. The BugBuilder virtual machine is based on a CentOS 7.2 installation, and is configured with a XFCE window manager to provide a graphical interface.

Once the virtual machine has finished loading, a window showing a terminal session and a firefox browser window will be displayed (see below).

2. Installing optional components

Certain components of the BugBuilder pipeline are restricted by licensing conditions which prevent their distribution with the virtual machine image. The pipeline is perfectly functional without these components but they may be advantageous to have installed in some circumstances. In particular, GapFiller can be used to automatically close gaps within scaffolds.

The components which are not available in the virtual machine can be readily installed, and a browser window will be opened in the virtual machine the first time it is run with links to the download locations of the packages. The desired packages should be downloaded to the /opt/BugBuilder/src directory (which is configured as the default download location for the web browser), following which the BugBuilder installation script should be run by typing 'configure.pl' in the terminal window, and pressing enter. This script will automatically install any additional packages which have been added to the src directory and configure BugBuilder to work with them.

3. User Account Details

The BugBuilder virtual machine will be automatically logged in as the 'BugBuilder' user. The password both for this user is 'BugBuilder'. If the network configuration of your virtual machine permits external connections to be made to the virtual machine, you will be able to connect to it directly via ssh using the BugBuilder username.

If you require root access to the virtual machine to change any of it's configuration, you can use the 'sudo -i' command when logged in as the BugBuilder user to gain root privileges, or use 'sudo' to run any other command directly. You will be prompted to enter the BugBuilder user's password before any sudo commands are executed.

4. Shutting down the VM

When you are finished working with the virtual machine, you should ideally shut it down rather than just closing the window. This can be done by clicking the 'BugBuilder' button in the top-right of the virtual machine window, then clicking the 'shutdown' menu item. The virtual machine will then be safely shutdown.