Running Genome Workbench over X Window System

• Introduction
• Installing on CentOs 7
• Installing on Ubuntu 18.04
• Installing on OpenSUSE 15.1
• Installing on Fedora 29
• Installing on Debian 9
• Enabling editing package
• Connecting from a Windows PC
• Connecting from a Mac
• VNC and X2Go
• Troubleshooting

Introduction

Why run Genome Workbench on the cloud? In addition to the usual benefits of being able to connect to the software from anywhere without the need to maintain your own server there are multiple other reasons. If your data processing pipeline already exists on the cloud it might be faster and more convenient to add Genome Workbench to your toolbox there instead of installing it on your desktop PC or Mac. Genome data sets can reach tens and hundreds of gigabytes in size. It may frequently be a non-trivial expense to move such amounts of data between the cloud storage and a desktop computer. A more cost effective approach would be to bring the software to the cloud instead of copying the data in the other direction. This guide gives step by step instructions on how to install Genome Workbench on Linux hosts running in the Amazon EC2 Cloud. This tutorial may also be useful if you are trying to install Genome Workbench on a Linux host running elsewhere.

See “connecting from a Windows PC” or “connecting from a Mac” directions to connect to the Linux host from Windows or Mac and display the Genome Workbench GUI. You also need to be familiar with the procedure to connect to the EC2 instances using ssh. Please see the Connecting to Your Linux Instance from Windows Using PuTTY notes if you are not already conversant with ssh.

Please note that configuration and launching of instances in AWS EC2 as well as the detailed tutorial on Genome Workbench usage for specific tasks is beyond the scope of this document.

The steps below assume Genome Workbench version 3.0.0. You can always find and download the latest release. As updated versions are made available, you may have to adjust the download URLs in the steps below. At the moment, the only supported architecture is x86_64. If your Linux host or AWS instance is running on an ARM CPU, you will have to build the software from source.

We used t2.large instance (8Gb RAM) for testing. You may select an instance with more or less RAM available, depending on your computational needs. The version of Linux running on an AWS instance needs to have some minimal set of tools installed (yum for CentOs, dnf for Fedora, zypper for OpenSUSE, apt for Ubuntu and Debian) as well as have sshd running. Some AWS images may not have even these tools available - CoreOs or AtomicHost versions of Fedora for example.

After launching and logging in to your instance via ssh, please issue each command from the command line exactly as written. Be aware of the accidental line-breaks – each step should constitute exactly one command – with the obvious exception of the instructions to the user, e.g. “log out and log back in…”

Installing on CentOs 7

1. sudo yum -y install epel-release
2. sudo yum -y install https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/ver-3.0.0/gbench-linux-centos7-x86_64-3.0.0.rpm
3. sudo yum -y install xorg-x11-xauth
4. logout and log back in to enable xauth, see notes for connecting from Windows or Mac.
5. /opt/ncbi/gbench-3.0.0/bin/gbench

Installing on Ubuntu Server 18.04 LTS

1. wget https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/ver-3.0.0/gbench-linux-Ubuntu-bionic_amd64-3.0.0.deb
2. sudo apt-get update
3. sudo apt install -y ./gbench-linux-Ubuntu-bionic_amd64-3.0.0.deb
4. /opt/ncbi/gbench-3.0.0/bin/gbench

Installing on OpenSUSE Leap 15.1

1. sudo zypper install -y Mesa-libglapi0
2. sudo rpm --import https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/GBENCH-GPG-KEY
3. sudo zypper install -y https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/ver-3.0.0/gbench-linux-openSUSE151-x86_64-3.0.0.rpm
4. sudo zypper install -y xauth
5. Log out and log back in to enable xauth, see notes for connecting from Windows or Mac.
6. /opt/ncbi/gbench-3.0.0/bin/gbench

Installing on Fedora 29

1. sudo dnf -y install https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/ver-3.0.0/gbench-linux-fedora29-x86_64-3.0.0.rpm
2. sudo dnf -y install xorg-x11-xauth
3. logout and log back in to enable xauth, see notes for connecting from Windows or Mac.
4. /opt/ncbi/gbench-3.0.0/bin/gbench

Installing on Debian 9

1. wget https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/ver-3.0.0/gbench-linux-debian9-amd64-3.0.0.deb
2. sudo apt-get update
3. sudo apt install -y ./gbench-linux-debian9-amd64-3.0.0.deb
4. sudo apt-get install -y xauth
5. Log out and log back in to enable xauth, see notes for connecting from Windows or Mac.
6. /opt/ncbi/gbench-3.0.0/bin/gbench

Genome Workbench GUI before the editing package is enabled.

Enabling editing package

After Genome Workbench is running and the GUI is displayed you may want to enable the editing package:

1. Invoke the Packages item in the Tools menu.
2. Select Sequence Editing.
3. If the Enable checkbox is not checked, please check it, click OK, and restart Genome Workbench (see screenshot).

Connecting from a Windows PC

To connect from a Windows PC you will need an ssh client (e.g. Putty or SecureCRT and an X-server for Windows (e.g. Xming or X-Win32).

1. Install X-server for Windows, for example Xming or X-Win32

2. Enable X-forwarding in your ssh client.

   • For putty:

   • For SecureCRT:

3. Connect to your Linux computer and start Genome Workbench from the command line. Make sure Xming or X-Win32 is running before connecting to the remote Linux system.

Connecting from Mac

1. Install X11 server for Mac - you will have to log out and login back after the installation.
2. Open Terminal and connect to the remote Linux system via ssh (do not forget -X command line option for X forwarding):
   ssh -X <remote hostname>
3. XQuartz server should start automatically. Launch Genome Workbench from the command line.

VNC and X2Go

Other approaches to use Genome Workbench GUI remotely without X-forwarding include VNC and X2Go. Both protocols allow for the full remote desktop experience similar to Windows Remote Desktop instead of a single application display. You will have to install a server component on the remote Linux host, as well as a complete desktop environment such as XFCE in addition to the client installed on your local Windows PC or Mac. You can find detailed instructions at the respective websites:

• TigerVNC
• RealVNC
• TightVNC
• X2Go

Troubleshooting

If you are experiencing problems running Genome Workbench on Linux and displaying the GUI on a Windows PC via X server such as X-Win32 please read the following instructions.

1. Are you unable to start Genome Workbench? The error in the terminal could be “Application terminated”. What to do: Verify that X-forwarding is enabled in your ssh client and that X-server is running on your local PC (XMing or X-Win32 for Windows). Also make sure that xauth utility is installed on the remote Linux host (typically found in /usr/bin/xauth) and that running “echo $DISPLAY” on Linux prints out something like: localhost:10.0

2. Are the colors wrong, or are the fonts corrupted?

This is what a few of our users reported seeing when running Genome Workbench.

What to do: Adjust the preferences in your X-Server emulator on the Windows PC (we used X-Win32): Make sure “PseudoColor” drop-down selection is set to “Emulation”.