This document guides you through the basics of installing and configuring openBIS. Its purpose it to allow newcomers to install openBIS and play with it, so exhaustive details are left out on purpose. The complete openBIS administration manual is maintained here Installation and Administrator Guide of the openBIS Server.
The successful installation of openBIS requires a machine with
- Linux or Mac OS X operating system
- PostgreSQL 9.6 or higher. You are required to have database superuser privileges (by default, the
postgresuser has those).
- Java 8 or higher. We recommend a recent Oracle / OpenJDK JRE.
Please, make sure all the prerequisites are met before continuing to the next chapters of this document.
Here are instructions on how to install the prerequisites on few most common Linux distributions:
Ubuntu Server 14.04.1 LTS 64bit
- When installing Ubuntu, select (at least) PostgreSQL to be installed
- When you are able to access the terminal, execute the following command:
- sudo apt-get install default-jre-headless unzip
CentOS 7 Minimal install
sudo yum install unzip postgresql-server java-1.8.0-openjdk-headless
- sudo systemctl enable postgresql
- sudo systemctl start postgresql
CentOS 7 Server with GUI
- When installing CentOS, select the following software to be installed
- Java framework
- PostgreSQL database
The basic openBIS deployment consists of two servers, the Application Server (AS) and the Data Store Server (DSS). Generally speaking, the AS manages the metadata and links to the data while the DSS manages the data itself. The AS employs a PostgreSQL server to persist users, authorization information, various entities and their metadata, as well as index information about all datasets. The DSS operates on a managed part of the file system (data store), where the data is kept. One AS can manage multiple DSS instances, which can make sense e.g. if the data are acquired in multiple, distributed laboratories each having a local DSS.
In this document we will describe an installation procedure with a single DSS, where all three servers (AS, DSS and PostgreSQL) run on the same computer. In general, each of them could be deployed on a dedicated machine, which would improve the overall performance of the system.
Note, that regardless of the particular deployment scenario, the servers must be started in the following order
- openBIS Application Server
- Data Store Server
This is required since the AS needs a running PostgreSQL server to start and the DSS needs an AS to boot up. These dependencies are depicted on the deployment overview diagram with arrows pointing from the dependent towards the dependee.
To avoid inconsistent states of the system, shutdowns must be executed backwards - starting from DSS and proceeding with AS and PostgreSQL respectively.
It is considered a good practice to install openBIS under a dedicated operating system user, but it is not mandatory to do so. Throughout the document we assume that openBIS will be installed and maintained by a user named
openbis. The default installation path for the system will be the home folder of
openbis. We also refer to the installation path as
PostgreSQL server configuration
Create a database user with the same name as the OS user (in our case
The openBIS setup assumes that PostgreSQL is configured with the trust setting on localhost, which means that a user connecting from
127.0.0.1 can connect without providing a password. These settings are changed in the file
pg_hba.conf, see http://www.postgresql.org/docs/9.3/static/auth-pg-hba-conf.html. If these settings are not correct, you will get an error of the form "Database role 'openbis' couldn't be created."
If the PostgreSQL server is configured correctly, then the following sequence of commands must return without errors.
Postgres on a remote server
When the database is on a remote server, the pg_hba.conf and postgresql.conf files need to be configured as follows:
So, the databse postgres need to be added to the file. Alternatively, instead of specifying each database and the postgres database, the database can be set to "all" as shown below:
Also have look here how to configure openBIS to connect to the remote Postgres DB.
Manual database creation
If openBIS cannot be allowed to create its own database (because of missing privileges, for example), you can use the script bin/init_database.sh (in your openBIS installation directory) that will create SQL statements to initialize the database. These SQL statememts can be given to be executed by a database administrator. Example:
- Go to openBIS Download Page.
- Download the latest release of openBIS installer. It should be a TAR.GZ archive and its name should look like
<version>is the release number (e.g. S117).
HCS users should download the screening installer -
Run the installation
NOTE: openBIS will ask you to provide the install directory. For a new installation this directory is created by the openBIS installer, so it should not already exist. If the directory already exists the installation will fail.
Extract the installation tarball
If you have a graphical environment (X server or comparable) you can run the openBIS installation wizard. Simply execute the
run-ui.sh script and follow the instructions on the screen.
To install openBIS on a headless system you need to
- Edit the file
- Execute the script
Congratulations ! If you have reached this far your openBIS system is installed and is ready to be started. Please do so by following the instructions in the next section.
The starting scripts of openBIS assume that
java is available on the system path, so you have to add it if this is not true.
Launch the openBIS AS and DSS servers by executing
To verify AS and DSS function and there are no configurational issues, please check the log files of the two applications using the
dsslog.sh scripts. Additionally, the openBIS application should be accessible at
https://localhost:8443/openbis and you should be able to login as the
admin user with the password specified in the installation process.
You can shutdown both the servers by executing the
Configure openBIS to run on one standard port 443
We would like all users who work in the network to use the standard https port (443) to access openbis and the DSS (datastore server).
We start openbis on port 8080 and DSS on port 8081. Those ports are not accessible from outside. Then we redirect all the requests to 443 port from outside to a right internal port depending on the URL suffix. We do this by switching on Apache forwarding (we use mod_proxy).
See the details below.
- we configure Apache instance (inside
/etc/httpd/conf.d/openbis.conffile on Linux, see attached openbis.conf as an example) to:
- redirect https://openbis-test.ethz.ch/openbis requests to http://openbis-test.ethz.ch:8080/openbis
- redirect https://openbis-test.ethz.ch/datastore_server requests to http://openbis-test.ethz.ch:8081/datastore_server
- use SSL for the requests. A certificate has a different format than the one used for openBIS. It should not use the password, to decrypt it you can use a command:
openssl rsa -in certificate.org.key > certificate.org.key.nopass
- by default the URL is escaped before the redirection happens (e.g. spaces are changed to %20). If your client already escapes the URL (openBIS does), you have to use
NErule to avoid escaping the URL twice.
We redirect http requests to https, with openbis appended at the end (when user connects to www.openbis-test.ethz.ch he is redirected to site automatically).
This is done in the file
/etc/httpd/conf/httpd.confon Linux by adding/changing following lines:
- we configure openbis and DSS servers not to use SSL (because Apache uses it already)
- install SSL module (mod_ssl) for Apache if it is not there:
yum install mod_ssl.
after changing the configuration you have to restart Apache. On Linux you call:
make sure that Apache will be restarted automatically
Create a file called
Rename the files
ssl.ini. These files are then then no longer used by jetty to serve at port 8443.
Settings for the Data Store Server (DSS)
These changes are needed for all Jetty versions which are used in openBIS
- do the same in DSS service.properties (sprint/datastore_server/etc) for 'server-url' and 'download-url' properties, additionally add
use-ssl = false
Changes to DSS service.properties file:
Upgrade server to newer version
Standard upgrade procedure
pg_dumpare present and accessible from the shell
- ssh to the server
- copy openBIS installation tarball (a.k.a. "Installation and Upgrade Wizard") to
<OPENBIS_HOME>/serversdirectory. You can download the latest version from here.
- read instruction about necessary configuration changes here.
Sometimes changes of the configuration are needed when a server is upgraded. You can do it after the upgrade. If you want to do this before, you can copy all the configuration of the servers to a temporary directory, modify it there and "apply" it to the upgraded server using
backup-config.sh <dir> and
restore-config-from-backup.sh <dir> scripts.
Upgrade installations with versions older than S118
The described upgrade steps are only valid for HCS installations prior S118 or for generic openBIS installations which have been created by the installation tarball. Generic openBIS installation assembled from two independent server archives (AS and DSS) are not be supported.
pg_dumpare present and accessible from the shell
- ssh to the server
- copy openBIS installation tarball (to temporary directory (e.g.
/tmp). You can download the latest version from here.
- read instruction about necessary configuration changes here.
extract the installation tarball
edit the file
console.propertiesand set the property
INSTALL_PATHto <OPENBIS_HOME> e.g.
./run-console.sh. The installation procedure will then upgrade the openBIS installation at
Changing server configuration
The most important configuration files of openBIS AS and DSS can be found in
Sometimes when many configuration files should be changed it can be convenient to copy all configuration files to one directory, modify them there and apply the changes. It can be done in the following way:
Execute the following command to copy all configuration files to a folder of your choice
- Modify the files in <directory-path>
Apply the configuration changes by executing
Configure JAVA options
datastore_server.conf contain the JVM options for the respective server. For recommendation on how to configure them see
Recommended Java and Postgres memory settings.
By default, the AS and DSS configurations assume a 64bit JDK. If you are running 32bit JDK you must remove the
-d64 parameter from
Configure authentication service
openBIS Application Server currently supports several authentication systems
file-authentication-service: a self-contained system based on a UNIX-like passwd file.
dummy-authentication-service: a "dummy" that allows everyone access to the system.
- Crowd system (see http://www.atlassian.com/software/crowd).
The latter two options will not be discussed in this document. For more information regarding LDAP or Crown integration check the Installation and Administrator Guide of the openBIS Server.
Dummy authentication service
If you only wish to play with openBIS and do not want to enforce security restrictions on the visiting users, you might want to choose the
To configure the dummy authentication scheme, edit
<OPENBIS_HOME>/server/openBIS-server/jetty/etc/service.properties and set the value of the property
File authentication service
The default installation procedure preconfigures openBIS with
file-authentication-service. It also creates the user acounts for
etlserver. If you wish to add more user accounts, you can do so with the help of the command line tool
<OPENBIS_HOME>/servers/openBIS-server/jetty/bin/passwd.sh by executing the following :
All passwords for
file-authentication-service are stored in the file
Configure database options
By default openBIS assumes that the database in accessible on localhost as a 'postgres' user with an empty password. To change that one has to edit
service.properties and configure the usernames and passwords for an PostgreSQL superuser (in sample below
postgres) and the user, which will take ownership of the openBIS database instance. Some of you have created this low-privileged user in #Create a database user for openBIS (optional).
It is permissible, albeit not advisable to configure the same user (e.g.
database.admin, providing the account is a PostgreSQL superuser.
Additionally, ensure the configured
database.kind property corresponds to the variable
OPENBIS_DB declared in the file
<OPENBIS_HOME>/bin/env. In our example
database.kind is configured as "demo", so the value of
OPENBIS_DB should be "openbis_demo".
Configure imaging database (HCS installations only)
For HCS installations you have to make a similar configuration for an additional database (imaging) in the DSS properties in servers/core-plugins/screening/NUM/dss/data-sources/imaging-db/plugin.properties file.
Please note that NUM is the highest number in the screening plugin. Currently this is 4.
This defines the username/passwords of an administrator user to perform migrations for the DSS database and an "owner" i.e. normal account to read/write data. In the example above the database will be called
imaging_productive. Make sure this name corresponds to the
IMAGING_DB variable in
You can create the "owner" database user as described in #Create a database user for openBIS (optional)
Additionally openBIS Application Server configuration has to be changed (usually
in servers/core-plugins/screening/NUM/as/dss-data-sources/DSS1/plugin.properties file)
Please note that NUM corresponds to the highest number in the screening plugin.
List of administration scripts
starts AS and DSS
stops AS and DSS
shows AS log file
shows DSS log file
Stores all configuration files in a specified directory
Overrides servers' configurations with the configuration from a specified directory (which can be created using
shows all current postgres queries (useful for debuging)
resets all users display settings (edit the
Contains instance specific settings. This file is not updated from SVN.
upgrades openBIS to the new version
List of important configuration files
Contains properties configuring the DSS process launch (e.g. JAVA options, number of log files).
DSS log configuration.
DSS application properties. This is the most important DSS configuration file.
Jetty server configuration (see http://docs.codehaus.org/display/JETTY/Syntax+Reference)
Supplementary Jetty properties
AS log configuration.
Contains properties configuring the AS process launch (e.g. JAVA options, number of log files).
AS application properties. This is the most important AS configuration file.
openBIS web UI configuration properties.
Altering file will change the login page of the openBIS web interface. Administrators can use this to add banners (e.g. with important announcements) visible to all users loggin in openBIS.