# Installation on Physical Clusters¶

## Prerequisites¶

There are two software requirements for the LigandScout Remote server application (iserver). These have to be installed on the host machine, that is part of the HPC cluster to be used for computations:

1. HPC cluster or computer running Linux
2. Java Version 1.8+
3. SGE, PBS, TORQUE, or SLURM Cluster Management Software (Scheduler). E.g.

## Installing the Server Application (iserver)¶

Tip

If you do not have access to a physical HPC cluster, you can skip this section and use LigandScout Remote in the AWS cloud.

Then, unpack the archive using the following command:

tar -xvzf iserver_*_.tar.gz


After unpacking, you will find a folder named ligandscout_server. Within that folder is a text file named application.properties. As discussed below, it is required to edit this file with some basic information about your environment in order to start using iserver.

## Mandatory Configuration¶

### Required Filesystem Paths¶

The application.properties file starts with a mandatory configuration section. Each of these options requires the setting of a filesystem path.

Info

Every filesystem path has to be accessible for all compute nodes as well as for the master node where the iserver application is running.

job.screening.directory=
job.confgen.directory=

Directory paths pointing to the location that the server will use for storing information about screening jobs and conformer generation jobs, respectively.

ligandscout.path=

Paths to the LigandScout installation folder, e.g.
iscreen.path.executable=/shared/software/ligandscout4/


This folder contains the LigandScout command-line tools iscreen, idbgen, libsize, and idbgmerger, which are used by iserver to submit computational workloads to the scheduling system.

# directories considered by the monitoring process, which looks for newly added compound databases (.ldb format required)
# multiple directories can be set separated by comma (,)
# Supports '*' as a wildcard on directory level, e.g. /shared/data/*/LDB matches /shared/data/molecules/LDB, /shared/data/compounds/LDB, and so on
ldb.directories=./ldb_databases
ldb.directories.monitoring.recursive=true

Filesystem location of .ldb screening databases. Multiple locations can be given via comma-separation, e.g:
ldb.directories=/shared/data/compound-databases/,/shared/data/screening-databases/


The * wildcard can be used to match all folders on a specific path level. If ldb.directories.monitoring.recursive is set to true (default), subdirectories of the given locations will also be searched for viable .ldb databases.

job.confgen.databases.directory=

Output directory for screening databses generated with the conformer generation feature of LigandScout Remote. If these databases should be available for screening, the directory also has to be added to the above described ldb.directories parameter.

ldb.directories.upload =

Directory for new screening databases uploaded via the LigandScout user interface. If these databases should be available for screening, the directory also has to be added to the above described ldb.directories parameter.

More advanced configuration is possible using the later sections of the application.properties file. Those are described in the server configuration section of this documentation.

### Working with SGE¶

SGE is currently the default resource manager (scheduler). Therefore, it is usually not required to adjust the configuration of iserver if SGE is used as scheduler.

Info

As of LigandScout Server 1.2.1, DRMAA is no longer required for SGE support if scheduler=sge-cmd is used.

### Working with SLURM¶

If the cluster resource manager (scheduler) in use is SLURM, you need to set the scheduler configuration option in the application.properties file to slurm i.e.

scheduler=slurm


### Working with UGE¶

If the cluster resource manager (scheduler) in use is UGE, you need to set the scheduler configuration option in the application.properties file to uge i.e.

scheduler=uge


### Working with PBS or TORQUE¶

If the cluster resource manager (scheduler) in use is PBS or TORQUE, you need to set the scheduler configuration option in the application.properties file to pbs or torque, because the default setting is sge, e.g.

scheduler=pbs


## Running the server¶

The iserver application is a conventional Java program. For convenience, a startup script is included that starts the .jar with reasonable default settings. The program can therefore be run by simply executing this script:

./iserver


Tip

It is recommended to create a dedicated system user for running iserver. All jobs submitted with iserver will belong to this new user. This approach helps administrators to manage and monitor scheduler resources.

### Using screen to Prevent Shutdown on Logout¶

In order to keep the server running after you quit your SSH/terminal session, we recommend using screen. Simply execute screen and the program will enter a session that lives on after you have logged out. From this session you can then execute the iserver startup script. To leave the screen session, use Ctrl-a.

Reference

Usage instructions for screen: https://help.ubuntu.com/community/Screen

### Starting the server on system startup¶

In most cases, it is desired to have iserver automatically start on system startup. The possible ways to do this depend on your operating system. Please consult with your system administrator and ask for the preferred way of adding a startup application.

One simple option is to use the Cron system. Start by typing

crontab -e

Then, add the iserver script via
@reboot /path/to/iserver


Warning

Please note that Cron is a simple and efficient method to achieve this, but it is most likely not the best method. For newer versions of Ubuntu, Debian, and CentOS we recommend to use the systemd init service. Furthermore, it is recommended to create a separate user for running the iserver application.

## Updating iserver¶

Warning

Please read the changelog for the version you want to update to. It is located at Version Dependencies. The changelog might give additional instructions or hints about new configuration settings you might want to use.

### Automatic Update using update.sh¶

Starting with isever 1.1.9, a script is included to help with the update process. The script allows to update from a downloaded installation archive or directly from the wwww.inteligand.com web servers:

\$  ./update.sh -h
Usage: update.sh [-v version] [-f local archive]

A script to update iserver to a specified version.
If no internet connection is available, a local archive can be used for updating.
Either '-v' or '-f' have to be set. If both options are supplied, '-v' is ignored.
It is recommended to stop the server process before starting the update procedure.

This script has to be located in the iserver installation directory.

Options:
-h  show this usage information
-v  version that should be downloaded and installed from www.inteligand.com, e.g. '1.1.8'
-f  local iserver installation archive file (*.tar.gz)


Before invoking the script, stop the iserver process. The script automatically downloads and extracts newer versions of ilib-server-<version>.jar and of the startup script iserver. If you made changes to the startup script, you will need to re-apply these changes after updating.

### Manual Update¶

To manually update an existing iserver installation, download the latest release from the link above and unpack the archive to a temporary directory:

mkdir temporary
mv iserver_*_.tar.gz temporary
cd temporary
tar -xvzf iserver_*_.tar.gz


Before continuing, stop the iserver process. Then, copy the files iserver and ilib-server-<version>.jar that have just been extracted from the tar.gz archive into the directory of your existing iserver installation. If there are existing files with the same names, replace them. You can then rename your installation directory to reflect the new server version, even though this is not required.
To summarize, updating only requires replacing the startup script iserver and the Java executable ilib-server-<version>.jar with the target version's files.