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¶
|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||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 Configuration instructions.
Debian Package Installation¶
Opal is available as a Debian package from OBiBa Debian repository. To proceed installation, do as follows:
RPM Package Installation¶
Opal is available as a RPM package from OBiBa RPM repository. To proceed installation, do as follows:
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
- 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¶
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' services: opal: image: obiba/opal:latest ports: - "8843:8443" - "8880:8080" links: - rock - mongo - mysqldata environment: - JAVA_OPTS=-Xms1G -Xmx8G -XX:+UseG1GC - OPAL_ADMINISTRATOR_PASSWORD=password - MONGO_HOST=mongo - MONGO_PORT=27017 - MYSQLDATA_HOST=mysqldata - MYSQLDATA_USER=opal - MYSQLDATA_PASSWORD=password - ROCK_HOSTS=rock:8085 volumes: - /tmp/opal:/srv mongo: image: mongo mysqldata: image: mysql:5 environment: - MYSQL_DATABASE=opal - MYSQL_ROOT_PASSWORD=password - MYSQL_USER=opal - MYSQL_PASSWORD=password rock: image: obiba/rock:latest
Then environment variables that are exposed by this image are:
||Java VM arguments.|
||Opal administrator password, required and set at first start.|
||MongoDB server host (optional).|
||MongoDB server port, default is
||MySQL server host for data storage (optional).|
||MySQL server port.|
||MySQL data database name.|
||MySQL data database user.|
||MySQL data database password.|
||MySQL server host for IDs storage (optional).|
||MySQL server port.|
||MySQL IDs database name.|
||MySQL IDs database user.|
||MySQL IDs database password.|
||Agate server host (optional).|
||Agate server port, default is
||Comma separated Rock R server URLs, for R server discovery (optional, but recommended).|
||Default Rock server administrator user name (optional).|
||Default Rock server administrator user password (optional).|
||Default Rock server manager user name (optional).|
||Default Rock server manager user password (optional).|
||Default Rock server user user name (optional).|
||Default Rock server user user password (optional).|
||R CRAN repositories (optional, see
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.
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:
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.
||yes||Path to the Opal “home” directory.|
||no||Options for the Java Virtual Machine. For example: -Xmx4096m -XX:MaxPermSize=256m|
To change the defaults update:
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):