Installation

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.

Requirements

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

Software	Suggested version	Download link	Usage
Java	21	OpenJDK downloads	Java runtime environment
PostgreSQL	>= 9.x	PostgreSQL	Database engine
MongoDB	>= 4.x	MongoDB Community downloads	Database engine
MySQL	>= 5.5.x	MySQL downloads	Database engine
R	>= 4.x	R downloads	Statistical analysis engine

Install

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 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
./opal-x-dist/bin/opal

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 User Directories to change it.

Docker Image Installation

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

The image needs no database server to run: since Opal 6.0.0 the configuration (projects, users, permissions, registered databases…) is kept in an embedded H2 database in the Opal home directory (see Configuration Database), and the data databases are registered afterwards, from the Administration > Databases page or through the environment variables below. The docker-opal repository has the complete docker compose files of the setups that follow.

Each setup puts its containers on a network of its own, on which the service names resolve (rock, mongo…) and which is named so that several stacks can coexist on a host without seeing each other.

Standalone

The smallest setup is Opal and a DataSHIELD ready R server, with no database server at all. This is enough to log in, work with resources and DataSHIELD, and register a data database later on:

services:
  opal:
    image: obiba/opal:latest
    networks:
      - opal-h2
    ports:
      - "8880:8080"
    depends_on:
      - rock
    environment:
      - OPAL_ADMINISTRATOR_PASSWORD=${OPAL_ADMINISTRATOR_PASSWORD}
      - ROCK_HOSTS=rock:8085
    volumes:
      - opal-home:/srv
  rock:
    image: obiba/rock:latest
    networks:
      - opal-h2
    volumes:
      - rock-home:/srv

volumes:
  opal-home:
  rock-home:

networks:
  opal-h2:
    name: opal-h2

With data databases

A typical setup including a MongoDB database and a PostgreSQL database (in addition to the DataSHIELD ready R server and all useful plugins) would be:

services:
  opal:
    image: obiba/opal:latest
    networks:
      - opal
    ports:
      - "8880:8080"
    depends_on:
      - rock
      - mongo
      - postgresdata
    environment:
      #- JAVA_OPTS=-Xms1G -Xmx8G -XX:+UseG1GC
      - OPAL_ADMINISTRATOR_PASSWORD=${OPAL_ADMINISTRATOR_PASSWORD}
      - MONGO_HOST=mongo
      - MONGO_PORT=27017
      - MONGO_USER=${MONGO_USER}
      - MONGO_PASSWORD=${MONGO_PASSWORD}
      - POSTGRESDATA_HOST=postgresdata
      - POSTGRESDATA_DATABASE=${POSTGRESDATA_DATABASE}
      - POSTGRESDATA_USER=${POSTGRESDATA_USER}
      - POSTGRESDATA_PASSWORD=${POSTGRESDATA_PASSWORD}
      - ROCK_HOSTS=rock:8085
    volumes:
      - opal-home:/srv
  mongo:
    image: mongo:8.0
    networks:
      - opal
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${MONGO_USER}
      - MONGO_INITDB_ROOT_PASSWORD=${MONGO_PASSWORD}
    volumes:
      - mongo-data:/data/db
  postgresdata:
    image: postgres:18
    networks:
      - opal
    environment:
      - POSTGRES_DB=${POSTGRESDATA_DATABASE}
      - POSTGRES_USER=${POSTGRESDATA_USER}
      - POSTGRES_PASSWORD=${POSTGRESDATA_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql
  rock:
    image: obiba/rock:latest
    networks:
      - opal
    volumes:
      - rock-home:/srv

volumes:
  opal-home:
  mongo-data:
  postgres-data:
  rock-home:

networks:
  opal:
    name: opal

All on PostgreSQL

The configuration database itself can be on a PostgreSQL server rather than embedded, with the POSTGRESCONFIG_* variables. As Opal writes its configuration to whatever database is configured at its first start, these variables must be there from the beginning: they cannot be added to an Opal that has already started once. A setup with one PostgreSQL server for the configuration and one for the data, and no MongoDB, would be:

services:
  opal:
    image: obiba/opal:latest
    networks:
      - opal-postgres
    ports:
      - "8880:8080"
    depends_on:
      - rock
      - postgresconfig
      - postgresdata
    environment:
      - OPAL_ADMINISTRATOR_PASSWORD=${OPAL_ADMINISTRATOR_PASSWORD}
      - POSTGRESCONFIG_HOST=postgresconfig
      - POSTGRESCONFIG_DATABASE=opal_config
      - POSTGRESCONFIG_USER=opal
      - POSTGRESCONFIG_PASSWORD=${POSTGRESCONFIG_PASSWORD}
      - POSTGRESDATA_HOST=postgresdata
      - POSTGRESDATA_DATABASE=opal
      - POSTGRESDATA_USER=opal
      - POSTGRESDATA_PASSWORD=${POSTGRESDATA_PASSWORD}
      - ROCK_HOSTS=rock:8085
    volumes:
      - opal-home:/srv
  postgresconfig:
    image: postgres:18
    networks:
      - opal-postgres
    environment:
      - POSTGRES_DB=opal_config
      - POSTGRES_USER=opal
      - POSTGRES_PASSWORD=${POSTGRESCONFIG_PASSWORD}
    volumes:
      - opal-config:/var/lib/postgresql
  postgresdata:
    image: postgres:18
    networks:
      - opal-postgres
    environment:
      - POSTGRES_DB=opal
      - POSTGRES_USER=opal
      - POSTGRES_PASSWORD=${POSTGRESDATA_PASSWORD}
    volumes:
      - opal-data:/var/lib/postgresql
  rock:
    image: obiba/rock:latest
    networks:
      - opal-postgres
    volumes:
      - rock-home:/srv

volumes:
  opal-home:
  opal-config:
  opal-data:
  rock-home:

networks:
  opal-postgres:
    name: opal-postgres

The configuration is then in the postgresconfig server, while the secret key that encrypts the credentials it holds is still in the Opal home volume: back up and restore the two together (see Configuration Database).

The environment variables that are exposed by this image are:

Environment Variable	Description
`JAVA_OPTS`	Java VM arguments.
`OPAL_ADMINISTRATOR_PASSWORD`	Opal administrator password, required and set at first start.
`APP_URL`	Opal public URL (optional, see `org.obiba.opal.public.url` setting).
`APP_CONTEXT_PATH`	Opal server URL context (optional, see `org.obiba.opal.server.context-path` setting).
`POSTGRESCONFIG_HOST`	PostgreSQL server host for the configuration database (optional, to be set before the first start; default is the embedded H2 database, see Configuration Database).
`POSTGRESCONFIG_PORT`	PostgreSQL server port for the configuration database, default is `5432`.
`POSTGRESCONFIG_DATABASE`	PostgreSQL configuration database name, an existing and empty database, default is `opal_config`.
`POSTGRESCONFIG_USER`	PostgreSQL configuration database user, default is `opal`.
`POSTGRESCONFIG_PASSWORD`	PostgreSQL configuration database password, required when `POSTGRESCONFIG_HOST` is set.
`MONGO_HOST`	MongoDB server host (optional).
`MONGO_PORT`	MongoDB server port, default is `27017`.
`MONGO_USER`	MongoDB server user (optional).
`MONGO_PASSWORD`	MongoDB server password (optional).
`MONGODATA_DATABASE`	MongoDB server data database name.
`MONGOIDS_DATABASE`	MongoDB server IDs database name (optional, ignored if a MySQL, MariaDB or PostgreSQL one is defined).
`MYSQLDATA_HOST`	MySQL server host for data storage (optional).
`MYSQLDATA_PORT`	MySQL server port 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 for IDs storage (optional).
`MYSQLIDS_DATABASE`	MySQL IDs database name.
`MYSQLIDS_USER`	MySQL IDs database user.
`MYSQLIDS_PASSWORD`	MySQL IDs database password.
`MARIADBDATA_HOST`	MariaDB server host for data storage (optional).
`MARIADBDATA_PORT`	MariaDB server port for data storage (optional).
`MARIADBDATA_DATABASE`	MariaDB data database name.
`MARIADBDATA_USER`	MariaDB data database user.
`MARIADBDATA_PASSWORD`	MariaDB data database password.
`MARIADBIDS_HOST`	MariaDB server host for IDs storage (optional, ignored if a MySQL one is defined).
`MARIADBIDS_PORT`	MariaDB server port for IDs storage (optional).
`MARIADBIDS_DATABASE`	MariaDB IDs database name.
`MARIADBIDS_USER`	MariaDB IDs database user.
`MARIADBIDS_PASSWORD`	MariaDB IDs database password.
`POSTGRESDATA_HOST`	PostgreSQL server host for data storage (optional).
`POSTGRESDATA_PORT`	PostgreSQL server port for data storage (optional).
`POSTGRESDATA_DATABASE`	PostgreSQL data database name.
`POSTGRESDATA_USER`	PostgreSQL data database user.
`POSTGRESDATA_PASSWORD`	PostgreSQL data database password.
`POSTGRESIDS_HOST`	PostgreSQL server host for IDs storage (optional, ignored if a MySQL or MariaDB one is defined).
`POSTGRESIDS_PORT`	PostgreSQL server port for IDs storage (optional).
`POSTGRESIDS_DATABASE`	PostgreSQL IDs database name.
`POSTGRESIDS_USER`	PostgreSQL IDs database user.
`POSTGRESIDS_PASSWORD`	PostgreSQL IDs database password.
`AGATE_URL`	Agate server URL (optional).
`AGATE_HOST`	[Deprecated, use `AGATE_URL`] Agate server host (optional).
`AGATE_PORT`	[Deprecated, use `AGATE_URL`] Agate server port, default is `8444`.
`ROCK_HOSTS`	Comma separated Rock R server URLs, for R server discovery (optional, but recommended).
`ROCK_ADMINISTRATOR_USER`	Default Rock server administrator user name (optional).
`ROCK_ADMINISTRATOR_PASSWORD`	Default Rock server administrator user password (optional).
`ROCK_MANAGER_USER`	Default Rock server manager user name (optional).
`ROCK_MANAGER_PASSWORD`	Default Rock server manager user password (optional).
`ROCK_USER_USER`	Default Rock server user user name (optional).
`ROCK_USER_PASSWORD`	Default Rock server user user password (optional).
`ROCK_POD_IMAGES_ALLOWED`	Comma separated list of allowed Rock pod images (optional), when Opal runs in a Kubernetes environment.
`ROCK_POD_SPECS`	Default Rock pod specifications in JSON format (optional), when Opal runs in a Kubernetes environment.
`R_REPOS`	R CRAN repositories (optional, see `org.obiba.opal.r.repos` setting).
`CSRF_ALLOWED`	Comma separated list of allowed CSRF origins (optional, see `csrf.allowed` setting).
`CSRF_ALLOWED_AGENTS`	Comma separated list of allowed client user agents, for requests without a `Referer` header (optional, see `csrf.allowed-agents` setting).
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry collector OTLP/HTTP URL, for instance `http://collector:4318` (optional). Setting it enables the log, trace and metric export: see OpenTelemetry.
`OTEL_SERVICE_NAME`	Name reported to the OpenTelemetry backend, default is `opal` (optional).
`OTEL_RESOURCE_ATTRIBUTES`	Comma separated `key=value` resource attributes added to every exported record (optional).

Kubernetes Installation

Some Helm chart values can be overridden by providing a values.yaml file: see default values.yaml.

The OBiBa Helm charts repository can be added with the following command:

helm repo add obiba https://www.obiba.org/helm-charts

The deployment then can be done using the following command:

helm install myopal obiba/opal

See Helm chart documentation for more details: OBiBa Opal chart README.

Upgrade

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.

Execution

Server launch

Service

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.

That file is the service’s environment: the OpenTelemetry settings go there too, see OpenTelemetry. Secrets belong in /etc/default/opal-secrets instead, which the service also reads and which can be made unreadable to the opal user.

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.

Manually

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

Rather than editing bin/opal or bin/opal.bat, which live in the distribution and are replaced by the next one, put these in OPAL_HOME/conf/opal-env.sh: the launch script sources it if it is there. The file ships in the distribution’s conf directory — copy it across if your OPAL_HOME predates it, as nothing writes into conf on your behalf. This is also where the OpenTelemetry settings go, see OpenTelemetry.

# OPAL_HOME/conf/opal-env.sh
export JAVA_OPTS="-Xms1G -Xmx2G -XX:+UseG1GC"

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

opal

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.

Docker

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

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

Usage

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

http://localhost:8080 will provide a connection without encryption,
https://localhost:8443 will provide a connection secured with ssl.

Troubleshooting

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.