Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


Opal is a stand-alone Java server application that does not require a database engine at installation time. Connection to one or more databases is part of the post-install configuration.


Server Hardware Requirements

Component Requirement
CPU Recent server-grade or high-end consumer-grade processor
Disk space 8GB or more (data are stored within the database, not in Opal server space).
Memory (RAM) Minimum: 4GB, Recommended: >8GB

Server Software Requirements

Java is the minimum software requirement, other software are for a fully functional system. While Java is required by Opal server application, MongoDB, MySQL, R can be installed on another server. See also :doc:`rserver`.

Software Suggested version Download link Usage
Java 8 OpenJDK 8 downloads Java runtime environment
MySQL >= 5.5.x MySQL downloads Database engine
MongoDB >= 2.4.x MongoDB downloads Database engine
R >= 3.0.x R downloads Statistical analysis engine


Opal is distributed as a Debian/RPM package, as a zip file and as a Docker image. The resulting installation has default configuration that makes Opal ready to be used. Once installation is done, see :doc:`configuration` instructions.

Debian Package Installation

Opal is available as a Debian package from OBiBa Debian repository. To proceed installation, do as follows:

  • Install Debian package. Follow the instructions in the repository main page for installing Opal.
  • Manage Opal Service: after package installation, Opal server is running: see Server launch.

RPM Package Installation

Opal is available as a RPM package from OBiBa RPM repository. To proceed installation, do as follows:

  • Install RPM package. Follow the instructions in the RPM repository main page for installing Opal.
  • Manage Opal Service: after package installation, Opal is running: see Server launch.

Zip Distribution Installation

Opal is also available as a Zip file. To install Opal zip distribution, proceed as follows:

  • Download Opal distribution
  • Unzip the Opal distribution. Note that the zip file contains a root directory named opal-x.y.z-dist (where x, y and z are the major, minor and micro releases, respectively). You can copy it wherever you want. You can also rename it.
  • Create an OPAL_HOME environment variable
  • Separate Opal home from Opal distribution directories (recommended). This will facilitate subsequent upgrades.

Set-up example for Linux:

mkdir opal-home
cp -r opal-x-dist/conf opal-home
export OPAL_HOME=`pwd`/opal-home

Launch Opal. This step will create/update the database schema for Opal and will start Opal: see Server launch.

For the administrator accounts, the credentials are "administrator" as username and "password" as password. See :ref:`user-dirs` to change it.

Docker Image Installation

OBiBa is an early adopter of the Docker technology, providing its own images from the Docker Hub repository.

A typical docker-compose file (including a MongoDB database and a MySQL database, a DataSHIELD ready R server and all useful plugins) would be:

version: '3'
    image: obiba/opal:latest
      - "8843:8443"
      - "8880:8080"
      - rock
      - mongo
      - mysqldata
      - JAVA_OPTS=-Xms1G -Xmx8G -XX:+UseG1GC
      - MONGO_HOST=mongo
      - MONGO_PORT=27017
      - MYSQLDATA_HOST=mysqldata
      - MYSQLDATA_USER=opal
      - MYSQLDATA_PASSWORD=password
      - ROCK_HOSTS=rock:8085
      - /tmp/opal:/srv
    image: mongo
    image: mysql:5
      - MYSQL_DATABASE=opal
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_USER=opal
      - MYSQL_PASSWORD=password
    image: obiba/rock:latest
      - /tmp/rock:/srv
      - ROCK_ADMINISTRATOR_NAME=administrator

Then environment variables that are exposed by this image are:

Environment Variable Description
OPAL_ADMINISTRATOR_PASSWORD Opal administrator password, required and set at first start.
MONGO_HOST MongoDB server host (optional).
MONGO_PORT MongoDB server port, default is 27017.
MYSQLDATA_HOST MySQL server host for data storage (optional).
MYSQLDATA_DATABASE MySQL data database name.
MYSQLDATA_USER MySQL data database user.
MYSQLDATA_PASSWORD MySQL data database password.
MYSQLIDS_HOST MySQL server host for IDs storage (optional).
MYSQLIDS_PORT MySQL server port.
MYSQLIDS_USER MySQL IDs database user.
MYSQLIDS_PASSWORD MySQL IDs database password.
AGATE_HOST Agate server host (optional).
AGATE_PORT Agate server port, default is 8444.
ROCK_HOSTS Comma separated Rock R server URLs, for R server discovery (optional, but recommended).
R_REPOS R CRAN repositories (optional, see org.obiba.opal.r.repos setting).

See also the Rock R server Docker documentation.


The upgrade procedures are handled by the application itself.

Debian Package Upgrade

If you installed Opal via the Debian package, you may update it using the command:

apt-get install opal

RPM Package Upgrade

If you installed Opal via the RPM package, you may update it using the command:

yum install opal-server

Zip Distribution Upgrade

Follow the Installation of Opal Zip distribution above but make sure you don't overwrite your opal-home directory.

Docker Distribution Upgrade

Change the docker image version and restart the docker container. If the opal-home directory was mounted in user space, it will be reused.


Server launch


When Opal is installed through a Debian/RPM package, Opal server can be managed as a service.

Options for the Java Virtual Machine can be modified if Opal service needs more memory. To do this, modify the value of the environment variable JAVA_ARGS in the file /etc/default/opal.

Main actions on Opal service are: start, stop, status, restart. For more information about available actions on Opal service, type:

service opal help

The Opal service log files are located in /var/log/opal directory.


The Opal server can be launched from the command line. The environment variable OPAL_HOME needs to be setup before launching Opal manually.

Environment variable Required Description
OPAL_HOME yes Path to the Opal "home" directory.
JAVA_OPTS no Options for the Java Virtual Machine. For example: -Xmx4096m -XX:MaxPermSize=256m

To change the defaults update: bin/opal or bin/opal.bat

Execute the command line (bin directory is in your execution PATH)):


The Opal server log files are located in OPAL_HOME/logs directory. If the logs directory does not exist, it will be created by Opal.


When using a docker-compose configuration file, the start up command is:

docker-compose -f docker-compose.yml up -d


To access Opal with a web browser the following urls may be used (port numbers may be different depending on HTTP Server Configuration):


If you encounter an issue during the installation and you can't resolve it, please report it in our Opal Issue Tracker.

Opal logs can be found in /var/log/opal. If the installation fails, always refer to this log when reporting an error.