installation-and-configuration-guide.md

Installation and Administrator Guide of the openBIS Server
==========================================================

## System Requirements

The minimal requirements of a system running openBIS are:

- Operating System: Linux / MacOS X (The binaries: `bash`, `awk`, `sed`, `unzip` need to be installed and in the `PATH` of the openBIS user.)
- Java Runtime Environment: recent versions of Oracle JRE 11
- PostgreSQL 11

We find Linux to be the easiest choice to get an openBIS server running quickly.

For recommended memory settings, see [Recommended CPU and memory settings for openBIS 20.10](./system-requirements.md).

An SMTP server needs to be accessible and configured if you want to obtain notifications.

## Installation

The server distribution is a `gzipped` `tar` file named `openBIS-installation-standard-technologies-<version>` `.tar.gz`. It contains:

- `console.properties:` configuration file for a console/non-gui installation

- `extract.sh:` helper script for installation

- `jul.config:` Log configuration for the openBIS install process

- `openBIS-installer.jar` Java archive containing openBIS

- `run-console.sh` Installation script for console/non-gui installation

- `run-ui.sh` Installation script for gui installation

### Installation steps

1. Create a service user account, i.e. an unprivileged, regular user account. **Do not run openBIS as root!**

2. Gunzip the distribution on the server machine into some temporary folder.

3. Run either the console/non-gui installation script or the gui installation script:

    **GUI-based installation**

    ```bash
    tar xvfz openBIS-installation-standard-technologies-S139.0-r26480.tar.gz
    cd openBIS-installation-standard-technologies-S139.0-r26480
    ./run-ui.sh
    ```

    In the non-gui version you have to edit the `console.properties`
    files:

    **Non-GUI installation**

    ```bash
    tar xvfz openBIS-installation-standard-technologies-S139.0-r26480.tar.gz
    cd openBIS-installation-standard-technologies-S139.0-r26480
    vi console.properties
    ./run-console.sh
    ```
    
    ```{note}
    Please be aware that the directory where openbis is installed should not already exist. Users should specify the directory where they want to install openBIS (in the console.properties or in the graphical installer) and this directory will be created by the installation procedure. If the directory already exists, the installation will fail.
    ```

After the successful installation you should have a look at the configuration file called s`ervice.properties`. It is located in `<server_folder>openBIS-server/jetty/etc/`

This file is a an [Extended Properties File](./optional-application-server-configuration.md). Here is an example which can be used as a template:

**service.properties**

```bash
# ---------------------------------------------------------------------------
# Database configuration
# ---------------------------------------------------------------------------
# The database instance local unique identifier. Used when the new database is created.
database-instance = DEFAULT

# Supported: currently only 'postgresql' is supported
database.engine = postgresql
database.url-host-part =
database.kind = prod
# User who owns the database. Default: Operating system user running the server.
database.owner =
database.owner-password =
# Superuser of the database. Default: database-dependent.
database.admin-user = 
database.admin-password =
# Max. number of active database connections. Default: 20. 
database.max-active-connections =
# Max. number of idle database connections to keep open. Default: 20. 
database.max-idle-connections = 
# Log interval (in seconds) between two regular log entries of the number of active database 
# connections. Default: 3600s.
database.active-connections-log-interval = 

# ---------------------------------------------------------------------------
# Master data by Excel sheets
# ---------------------------------------------------------------------------
# Path to the file which stores version information of master data imported from Excel sheets. 
# Default value: ../../../xls-import-version-info.json. The file will be created. 
# It should be <openbis installation path>/servers/openBIS-server. 
# Note, that the folder containing this file has to exist. 
# xls-import.version-data-file = ../../../xls-import-version-info.json

# ---------------------------------------------------------------------------
# Authentication configuration
# ---------------------------------------------------------------------------
# Supported Authentication options are:
# 'file-authentication-service'
# 'ldap-authentication-service'
# 'crowd-authentication-service'
# 'file-crowd-authentication-service'
# 'file-ldap-authentication-service'
# 'ldap-crowd-authentication-service'
# 'file-ldap-crowd-caching-authentication-service'
# For a detailed description, have a look at the Installation and Administrator
# Guide of the openBIS Server: https://wiki-bsse.ethz.ch/x/oYIUBQ 
authentication-service = file-ldap-crowd-caching-authentication-service

# ---------------------------------------------------------------------------
# Caching configuration (only used with 'file-ldap-crowd-caching-authentication-service')
# ---------------------------------------------------------------------------
# The time that the authentication cache keeps entries. Default: 28h
authentication.cache.time = 28h
# The time that the authentication cache does not perform re-validation on a cache entry. 
# Default: 1h
authentication.cache.time-no-revalidation = 1h

# ---------------------------------------------------------------------------
# Crowd configuration
# ---------------------------------------------------------------------------
#
# The Crowd host.
# Mandatory.
crowd.service.host = 
# The Crowd service port. Default: 443
crowd.service.port =
# The timeout (in s) to wait for a Crowd query to return, -1 for "wait indefinitely". Default: 10s. 
crowd.service.timeout =
# The Crowd application name. The value 'openbis' is just a suggestion.
# Mandatory. 
crowd.application.name = openbis
# The Crowd application password. 
# Mandatory.
crowd.application.password =

# ---------------------------------------------------------------------------
# LDAP configuration
# ---------------------------------------------------------------------------
# The space-separated URLs of the LDAP servers, e.g. "ldap://d.ethz.ch/DC=d,DC=ethz,DC=ch". 
# Mandatory.
ldap.server.url = 
# The distinguished name of the security principal, e.g. "CN=carl,OU=EthUsers,DC=d,DC=ethz,DC=ch".
# Mandatory.
ldap.security.principal.distinguished.name = 
# Password of the LDAP user account that will be used to login to the LDAP server to perform the queries. 
# Mandatory.
ldap.security.principal.password = 
# The security protocol to use, use "ssl" or "none", default is "ssl"
ldap.security.protocol =
# The authentication method to use: "none" (no authentication), "simple", "strong" (SASL), defaults to "simple"
ldap.security.authentication-method =
# The referral mode:
# "follow" - follow referrals automatically (the default)
# "ignore" - ignore referrals
# "throw" - throw ReferralException when a referral is encountered
ldap.referral =
# The attribute name for the user id, defaults to "uid"
ldap.attributenames.user.id =
# The attribute name for the email, defaults to "mail"
ldap.attributenames.email =
# The attribute name for the first name, defaults to "givenName"
ldap.attributenames.first.name =
# The attribute name for the last name, defaults to "sn"
ldap.attributenames.last.name =
# Set to true to also query for email aliases
ldap.queryEmailForAliases = true
# The query template, needs to contain %s which will be filled with the query term, e.g. uid=username
# The default is:
# ldap.queryTemplate = (&(objectClass=organizationalPerson)(objectCategory=person)(objectClass=user)(%s))
# which is known to work for many Active Directory installations.
# For OpenLDAP, replace by: 
# ldap.queryTemplate = (&(%s))
# For restriction to BSSE accounts in OpenLDAP, set to: 
# ldap.queryTemplate = (&(objectClass=bssePosixAccount)(%s))
ldap.queryTemplate =
# The number of times a failed LDAP query is retried at the max. Default: 1.
ldap.maxRetries = 
# The timeout (in s) to wait for an LDAP query to return, -1 for "wait indefinitely". Default: 10s. 
ldap.timeout = 
# The time (in s) to wait after a failure before retrying the query. Default: 10s. 
ldap.timeToWaitAfterFailure =

# ---------------------------------------------------------------------------
# Anonymous login configuration (optional)
# ---------------------------------------------------------------------------
# Login of the existing user whose settings will be used for anonymous login 
#user-for-anonymous-login = <user-login>