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 |
8 |
Java runtime environment |
|
MySQL |
>= 5.5.x |
Database engine |
|
MongoDB |
<= 6.0.x |
Database engine |
|
R |
>= 4.x |
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:
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 variableSeparate 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.
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:
- "8880:8080"
links:
- rock
- mongo
- mysqldata
environment:
#- JAVA_OPTS=-Xms1G -Xmx8G -XX:+UseG1GC
- OPAL_ADMINISTRATOR_PASSWORD=${OPAL_ADMINISTRATOR_PASSWORD}
- MONGO_HOST=mongo
- MONGO_PORT=27017
- MYSQLDATA_HOST=mysqldata
- MYSQLDATA_DATABASE=${MYSQLDATA_DATABASE}
- MYSQLDATA_USER=${MYSQLDATA_USER}
- MYSQLDATA_PASSWORD=${MYSQLDATA_PASSWORD}
- ROCK_HOSTS=rock:8085
volumes:
- /some/path/opal:/srv
mongo:
image: mongo:6.0
mysqldata:
image: mysql
environment:
- MYSQL_DATABASE=${MYSQLDATA_DATABASE}
- MYSQL_USER=${MYSQLDATA_USER}
- MYSQL_PASSWORD=${MYSQLDATA_PASSWORD}
- MYSQL_RANDOM_ROOT_PASSWORD=yes
rock:
image: obiba/rock:latest
The environment variables that are exposed by this image are:
Environment Variable |
Description |
---|---|
|
Java VM arguments. |
|
Opal administrator password, required and set at first start. |
|
Opal public URL (optional, see |
|
Opal server URL context (optional, see |
|
MongoDB server host (optional). |
|
MongoDB server port, default is |
|
MongoDB server user (optional). |
|
MongoDB server password (optional). |
|
MongoDB server data database name. |
|
MongoDB server IDs database name (optional, ignored if a MySQL, MariaDB or PostgreSQL one is defined). |
|
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. |
|
MariaDB server host for data storage (optional). |
|
MariaDB data database name. |
|
MariaDB data database user. |
|
MariaDB data database password. |
|
MariaDB server host for IDs storage (optional, ignored if a MySQL one is defined). |
|
MariaDB IDs database name. |
|
MariaDB IDs database user. |
|
MariaDB IDs database password. |
|
PostgreSQL server host for data storage (optional). |
|
PostgreSQL data database name. |
|
PostgreSQL data database user. |
|
PostgreSQL data database password. |
|
PostgreSQL server host for IDs storage (optional, ignored if a MySQL or MariaDB one is defined). |
|
PostgreSQL IDs database name. |
|
PostgreSQL IDs database user. |
|
PostgreSQL IDs database password. |
|
Agate server URL (optional). |
|
[Deprecated, use |
|
[Deprecated, use |
|
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.
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.
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 |
---|---|---|
|
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: bin/opal
or bin/opal.bat
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.