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:
- HPC cluster or computer running Linux
- Java Version 1.8+
- 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.
Start by downloading iserver from the official Inte:Ligand download servers:
https://www.inteligand.com/download/iserver/iserver_1.3.3_linux64.tar.gz
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=
ligandscout.path=
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
.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=
ldb.directories parameter.
ldb.directories.upload =
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
@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.