2. Installing and Initializing¶

2.1. Installation Under Windows¶

Double-click on the self-extracting executable (VarSeq-Win32-2.2.5.exe or VarSeq-Win64-2.2.5.exe). It will open up an install dialog screen.

The default is to install the software in the users application data folder which is approximately:

C:\Users\<User Name>\AppData\Local\Golden Helix\VarSeq\Application\

Under Windows, you also have the option of adding a VarSeq program icon to your desktop, a Quick Launch icon, and having VarSeq available from the Start Menu.

Once VarSeq is installed, you can run the program either by using the shortcuts or by running the executable. This will launch the login and registration dialog. If you already have a VarSeq account, enter in your credentials to launch the application. Otherwise register an email address and a license key to launch the application.

2.2. Installation Under Ubuntu or Compatible Distributions¶

Download the VarSeq archive for Lin64 to a convenient user directory.
The bundle is a “.tar.gz” archive file that will extract a folder called “VarSeq”. You can extract the archive using Linux GUI or command line tools. On the command line perform the following command:
```
~/Programs/> tar -xzvf VarSeq-Lin64-2.0.0.tar.gz
```
Once extracted, you can move the resulting VarSeq folder to another location of your choice at any time.
Go into the VarSeq folder and run the VarSeq App. The program will launch and present the login and registration dialog. If you already have a VarSeq account enter in your credentials to launch the application. Otherwise register an email address and to create an account to launch the application. You can do this with the following commands:
```
~/Programs/> cd "VarSeq"
~/Programs/VarSeq> ./VarSeq
```

Note

You may add the VarSeq folder to your path so that it can be launched from any directory. This also allows you to run scripts from various directories.

Note

You may need to install some system GUI libraries on your system by running:

sudo apt-get install libqt5gui5

Our Linux binaries are compiled on Centos7 for maximum compatibility with most Linux distributions. Known incompatibilities exist with Red Hat Enterprise Linux (RHEL) and CentOS version 6 and earlier. RHEL versions 7.x and newer are supported as well as Ubuntu version 14.04 and newer. If you have RHEL/CentOS 7.x see the instructions below Installation Under RHEL7 and CentOS7 Linux Distributions.

Please contact support if your experience issues running VarSeq on your Linux machine.

2.3. Installation Under RHEL7 and CentOS7 Linux Distributions¶

Download the VarSeq archive for RHEL to a convenient user directory.
The bundle is a “.tar.gz” archive file that will extract a folder called ” VarSeq “. You can extract the archive using Linux GUI or command line tools. On the command line perform the following command:
```
~/Programs/> tar -xzvf VarSeq-RHEL-2.0.0.tar.gz
```
Once extracted, you can move the resulting VarSeq folder to another location of your choice at any time.
Go into the VarSeq folder and run the VarSeq App. The program will launch and present the login and registration dialog. If you already have a VarSeq account enter in your credentials to launch the application. Otherwise register an email address and to create an account to launch the application. You can do this with the following commands:
```
~/Programs/> cd "VarSeq"
~/Programs/ VarSeq > ./VarSeq
```

Note

You may need to install some system GUI libraries on your system by running:

sudo yum install qt5-qtbase-gui.x86_64

Our Linux binary is compiled on CentOS7 for compatibility with RHEL/CentOS versions 7.x and higher.

Please contact support if your experience issues running VarSeq on your Linux machine.

2.4. Linux Configuration in a Shared Environment¶

It is possible to configure a Linux installation to be used in a multi-user environment. Following these instructions will allow users to use the same annotation sources and have access to other users’ projects. Note that depending on system configuration you may need to execute these commands as a super user (ie “sudo <cmd>”).

Note

After configuring your installation, be sure to “Log Out” in VarSeq when finished with your analysis. If you do not log out, the next user to open VarSeq will be automatically logged in as the previous user. You can un-check the “Stay logged in” box to always log out. If you would like to be automatically logged out, please contact support and your license can be set to automatically log out when the program is closed.

Create a group that all VarSeq users on the system can be members of. You can do this with the following command:
```
groupadd VSUsers
```

Add all VarSeq users to the group you just created. You can do this with the following commands:

usermod -a -G VSUsers user1
usermod -a -G VSUsers user2
usermod -a -G VSUsers user3

Install VarSeq to a directory that all users have access to. In this example we will use “/opt”. You can do this with the following commands:
```
cd /opt
tar -xvzf VarSeq-Lin64-[version number].tar.gz
```
Create a shared data directory on the system in a location all users have access to. You can do this with the following commands:
```
cd /opt
mkdir SharedData
```
Add a symlink from a directory named “AppData” in the VarSeq installation directory to the shared data directory. You can do this with the following commands:
```
cd /opt/VarSeq
ln -s /opt/SharedData AppData
```
Launch VarSeq to create the necessary directory structure in the new shared data folder.
Modify the ownership of the installation directory and shared directory so that all users in the previously created group can write to these directories. You can do this with the following commands:
```
cd /opt
chown -R :VSUsers SharedData
chown -R :VSUsers VarSeq
```

Note

In order for VarSeq to correctly access this directory structure, the umask setting must be “002”. This is the default for most linux distributions.

Your system should now be configured to share data between users. The new directory structure should look like:

opt
|-- [user1 VSUsers]  SharedData
|   |-- [user1 VSUsers]  Common Data
|   |   |--[user1 VSUsers]  Annotations
|   |   |-- [user1 VSUsers]  Assemblies
|   |   |-- [user1 VSUsers]  Cache
|   |   |-- [user1 VSUsers]  WebCache
|   |-- [user1 VSUsers]  VarSeq
|       |-- [user1 VSUsers]  User Data
|           |-- [user1 VSUsers]  ProjectTemplates
|-- [user1 VSUsers]  VarSeq
    |-- [user1 VSUsers]  AppData -> /opt/SharedData
    |-- [user1 VSUsers]  Data
    |-- [user1 VSUsers]  lib
    |-- [user1 VSUsers]  plugins
        |-- [user1 VSUsers]  imageformats

Note

VarSeq places the current users preferences, logged in state and some path configurations in a text based properties file under ~/.local/share/Golden Helix/VarSeq/User Data/vsprops.json. You can control the base path that defaults to ~/.local/share/Golden Helix/ by setting the GOLDENHELIX_USERDATA environment variable before running VarSeq.

2.5. Installation Under Mac OS X¶

Download the VarSeq app bundle for Mac to a convenient temporary directory.
Run the installer by double clicking on the package and click and drag the VarSeq application into the Applications folder.
Go into the VarSeq folder and run the VarSeq App. The program will launch the login and registration dialog. If you already have a VarSeq account enter in your credentials to launch the application. Otherwise register an email address and to create an account to launch the application.

Note

Mac OS 10.11 or higher is required for VarSeq

2.6. Setting System Defaults with hosts.json File¶

A number of defaults for running VarSeq can be controlled by an optional hosts.json file that resides in the program folder (next to the VarSeq executable). These include a flag to limit annotation source selection to already downloaded tracks if available and a default URL for VSWarehouse.

To create a hosts.json file, you can first open VarSeq, then go to Tools > Open Folder > Program Folder. This will take you to the location of the VarSeq binary (on Mac, it will take you to the VarSeq.app/Contents folder). At this location, create a new file called hosts.json and edit it using a text editor (Note it should not have a .txt extension). See blow for example configuration options.

2.6.1. Use Only Local Sources as Latest¶

In a multi-user or clinical environment, it may make sense to not use the latest version of sources published to the public and secure annotation sources when running VarSeq or VSClinical.

Create the following hosts.json to change this behavior:

{
  "localOnlyLatest": true
}

When you start VarSeq, you can see in the Help > About dialog if this flag has been set under the “Use Latest Remote Sources on Add” label.

With this flag set, the following behavior will be different:

Any opened or recently completed project will show out-of-date notifications in the upper-right for only locally downloaded annotation sources that are newer than the ones used to create the project.
Similarly, VSClinical will not show in the source version dialogs update notifications for sources that have not been downloaded.
Adding algorithms to VarSeq that have additional dependencies such as the ACMG Classifier for Variants or CNVs will select the latest local version of those dependencies if available instead of downloading the latest version from the data servers.

Note that with this flag set, you can still see and download any updated annotation source manually through the Tools > Manage Data Sources dialog by browsing the Public Annotations and Secure Annotations repositories.

It is common for labs to use a shared annotations folder by all VarSeq users. Using this flag, updates can be done manually monthly or quarterly by downloading the latest version of sources like ClinVar and OMIM using this dialog. This way, all other users are not prompted to perform updates in their analysis workflows that would have implications for all other users of the shared annotations folder.

2.6.2. Change the News Feed URL¶

If your organization has a specific internal help-desk or a VarSeq support website you would like to display to users on the right-side of the welcome screen to replace the VarSeq news feed, you can customize the URL for all users.

Create the following hosts.json to change this behavior:

{
  "news_feed": "http://internal-lab-domain.local/varseq-support/"
}

2.6.3. Preset the VSWarehouse URL¶

If your organization has a VSWarehouse server and multiple users, you can configure VarSeq to have the VSWarehouse URL preset for all new users.

Create the following hosts.json to change this behavior:

{
  "warehouse": "http://warehouse.internal-lab-domain.local"
}

You can create a hosts.json with both of these options as well:

{
  "localOnlyLatest": true,
  "warehouse": "http://warehouse.internal-lab-domain.local"
}