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 :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
- 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 :ref:`user-dirs` 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 volumes: - /tmp/rock:/srv environment: - ROCK_ADMINISTRATOR_NAME=administrator - ROCK_ADMINISTRATOR_PASSWORD=password
Then environment variables that are exposed by this image are:
||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).|
||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):
- http://localhost:8080 will provide a connection without encryption,
- https://localhost:8443 will provide a connection secured with ssl.
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.