Child pages
  • openBIS setup guide
Skip to end of metadata
Go to start of metadata


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.0 or higher. You are required to have database superuser privileges (by default, the postgres user has those).
  • Java 1.5 or higher. We recommend a recent Oracle / OpenJDK JRE 1.6.

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.7.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

Deployment overview

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

  1. PostgreSQL
  2. openBIS Application Server
  3. 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 OPENBIS_HOME.

PostgreSQL server configuration

Create a database user with the same name as the OS user (in our case openbis)

$ sudo -u postgres createuser openbis 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

The openBIS setup assumes that PostgreSQL is configured with the trust setting on localhost, which means that a user connecting from can connect without providing a password. These settings are changed in the file pg_hba.conf, see 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.

> su - openbis
> psql -U postgres -l
> psql -l

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/ (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:

$ bin/ openbis_dev openbis

-- Execute the following SQL script as a database superuser
create user openbis;
create database openbis_dev with owner openbis encoding 'UTF8' template=template0 tablespace=pg_default;
alter database openbis_dev set default_with_oids = off; 
alter database openbis_dev set join_collapse_limit = '32'; 
alter database openbis_dev set from_collapse_limit = '32'; 

\connect openbis_dev

create table database_version_logs(db_version varchar(4) not null, module_name varchar(250), run_status varchar(10), run_status_timestamp timestamp, module_code bytea, run_exception bytea);
insert into database_version_logs(db_version, run_status, run_status_timestamp) values ('0', 'SUCCESS', now());
alter database openbis_dev owner to openbis;
alter table database_version_logs owner to openbis;
1st argument to the script is the name of the database to be created.
2nd argument to the script is the name of the user openBIS will use to access the database we created.
Note: both the database name and user name need to be reflected in configuration files.

Download binaries

  • 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 openBIS-installation-<version>-r<revision>.tar.gz, where <version> is the release number (e.g. S117).
$ ls -a 

HCS users should download the screening installer - openBIS-installation-screening-<version>-r<revision>.tar.gz

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

> tar xzvf openBIS-installation-S117-r23517.tar.gz
x openBIS-installation-S117-r23517/
x openBIS-installation-S117-r23517/jul.config
x openBIS-installation-S117-r23517/
x openBIS-installation-S117-r23517/
x openBIS-installation-S117-r23517/
x openBIS-installation-S117-r23517/openBIS-installer.jar

Graphical installation

If you have a graphical environment (X server or comparable) you can run the openBIS installation wizard. Simply execute the script and follow the instructions on the screen.

> cd openBIS-installation-S117-r23517
> ./

Headless installation

To install openBIS on a headless system you need to

  • Edit the file
  • Execute the script
> cd openBIS-installation-S117-r23517
> ./

Congratulations (thumbs up) ! 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 <OPENBIS_HOME>/bin/

$ ./bin/

To verify AS and DSS function and there are no configurational issues, please check the log files of the two applications using the and 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 <OPENBIS_HOME>/bin/ script

$ ./bin/

Upgrade server to newer version

Standard upgrade procedure


  • java, psql, pg_dump are present and accessible from the shell

Upgrade steps:

  • ssh to the server
  • copy openBIS installation tarball (a.k.a. "Installation and Upgrade Wizard") to <OPENBIS_HOME>/servers directory. You can download the latest version from here.
  • read instruction about necessary configuration changes here.
  • run <OPENBIS_HOME>/bin/

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 <dir> and <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.


  • java, psql, pg_dump are present and accessible from the shell

Upgrade steps:

  • 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

    > tar xzvf openBIS-installation-S117-r23517.tar.gz
  • edit the file and set the property INSTALL_PATHto <OPENBIS_HOME> e.g.

  • execute ./ The installation procedure will then upgrade the openBIS installation at INSTALL_PATH.

Changing server configuration

The most important configuration files of openBIS AS and DSS can be found in openBIS-server/jetty/etc and datastore_server/etc folders.

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

    $ ./bin/ <directory-path>
  • Modify the files in <directory-path>
  • Apply the configuration changes by executing

    $ ./bin/ <director-path>

Configure JAVA options

The files openbis.conf and datastore_server.conf contain the JVM options for the respective server. For recommendation on how to configure them see
Recommeded 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 openbis.conf and datastore_server.conf.

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.
  • LDAP
  • Crowd system (see

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 dummy-authentication-service.

To configure the dummy authentication scheme, edit <OPENBIS_HOME>/server/openBIS-server/jetty/etc/ and set the value of the property authentication-service to dummy-authentication-service.
authentication-service = dummy-authentication-service

File authentication service

The default installation procedure preconfigures openBIS with file-authentication-service. It also creates the user acounts for admin and 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/ by executing the following :

$ add [-f <first name>] [-l <last name>] [-e <email>] admin
Enter new password: *****

All passwords for file-authentication-service are stored in the file <OPENBIS_HOME>/servers/openBIS-server/jetty/etc/passwd.

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 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. postgres) for database.owner and database.admin, providing the account is a PostgreSQL superuser.
# Part of the name of the database. The full name of the database will be openbis_<kind>.

# ID of the user owning the data. In case of an empty string it is the same user who 
# started up openBIS Application Server.
database.owner = openbisdbuser
database.owner-password = *******

# ID of the user on database server with admin rights, like creation of tables. 
# Should be an empty string if default admin user should be used. In case of PostgreSQL 
# the default admin user is assumed to be postgres
database.admin-user = postgres
database.admin-password = *******

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 (usually in servers/datastore_server/etc/ file).
data-sources = imaging-db
imaging-db.basicDatabaseName = imaging
imaging-db.databaseKind = productive
imaging-db.owner = dssdbuser
imaging-db.password = *******
imaging-db.adminUser = postgres 
imaging-db.adminPassword = *******

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 <OPENBIS_HOME>/bin/env.

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/openBIS-server/jetty/etc/ file)

<dss-based-data-source-provider>.<dss-code>.database-url = jdbc:postgresql://<hostname>/<database-name>
<dss-based-data-source-provider>.<dss-code>.database-username = dssdbuser
<dss-based-data-source-provider>.<dss-code>.database-password = *******


List of administration scripts


Startup/shutdown scripts


starts AS and DSS

stops AS and DSS

starts AS

stops AS

shows AS log file

starts DSS

stops DSS

shows DSS log file

Utility scripts


Stores all configuration files in a specified directory

Overrides servers' configurations with the configuration from a specified directory (which can be created using and modified afterwards).

shows all current postgres queries (useful for debuging)

resets all users display settings (edit the TEMPLATE_USER variable first)

Installation scripts



Contains instance specific settings. This file is not updated from SVN.

upgrades openBIS to the new version

List of important configuration files


Configuration file



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

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.

  • No labels