Installation of Opal 2.4.x on Debian/Linux

Installation of Opal 2.4.x on
Debian/Linux
This manual is based on the online Opal documentation (http://wiki.obiba.org/display/OPALDOC).
It describes how to install and setup Opal, R server and database on Debian 8.
1 Requirements
In case that all of the applications (Opal, R server and database) will run on the same host system
(real hardware or virtual server), following requirements are proposed:
•
Server CPU or high-end-consumer CPU
•
Memory >= 8G
•
Disk Space >= 10GB
A successful installation requires a pre-installed and running Debian 8 system. Before installing
applications you have to check if:
•
you have terminal access (direct or via ssh)
•
your user account has administration rights (with sudo)
•
the target system has Internet access
2 Installation of Opal Server
During the installation some of thee system tools provided by Debian/Linux will be used frequently.
One of them is sudo. This tool allows you to execute any following command with administrator
privileges (as root user). Another tool is apt-get. This is a command line tool for handling with
packages on Debian. It will be used for installing software from repositories.
2.1
Installation of Java
Opal server is an Java-application that's why Java Runtime Environment is required. With apt-Tool
you can install Java with following command:
sudo apt-get -y install openjdk-7-jre
2.2
Installation of Database
Opal server uses database for storing data. It supports some different database engines such as
MySQL or MongoDB. In this step you will install MariaDB which is a MySQL-compatible but also
faster database.
With the following command you can install MariaDB server:
sudo apt-get -y install mariadb-server
During the installation you will be asked for setting a password for the database administrative user
(root). Please chose your passwords carefully according to your security policies. Remember it
because you will need it for the database configuration later. Put in and confirm the password.
Opal installation guide recommends to change the default database character setting to utf8. Open
the configuration file /etc/mysql/conf.d/mariadb.cnf with a text editor (vi, nano or what you prefer)
and change default-character-set in [client] section and character-set-server and collation-server in
[mysqld] section. View the example below:
# MariaDB-specific config file.
# Read by /etc/mysql/my.cnf
[client]
# Default is Latin1, if you need UTF-8 set this (also in server section)
default-character-set = utf8
[mysqld]
#
# * Character sets
#
# Default is Latin1, if you need UTF-8 set all this (also in client section)
#
character-set-server = utf8
collation-server
= utf8_bin
Restart the database server as follows to apply the changes:
sudo service mysql restart
In the next steps some databases will be created which Opal will be connected to. Log in into the
database shell with the root password you set before:
mysql -u root -p
After successful login you will see the database prompt and can continue the setup.
MariaDB [(none)]>
At first you have to create databases for data and identifiers which are required for Opal:
CREATE DATABASE opal_data CHARACTER SET utf8 COLLATE utf8_bin;
CREATE DATABASE opal_ids CHARACTER SET utf8 COLLATE utf8_bin;
Then you create 'opal' user in the database as
<password_for_opal_user> with a password of your choice:
follows,
whereby
replacing
CREATE USER 'opal'@'localhost' IDENTIFIED BY '<password_for_opal_user>';
At last you will allow access for user 'opal' to the previously created databases opal_data and
opal_ids databases from local host:
GRANT ALL ON opal_data.* TO 'opal'@'localhost';
GRANT ALL ON opal_ids.* TO 'opal'@'localhost';
FLUSH PRIVILEGES;
and leave the MariaDB shell with
QUIT
2.3
Installation of Opal
Before installing the Opal application, you have to do some more preparations. At first the apt-Tool
has to be extended with the ability to communicate to OBiBa’s repository via HTTPS protocol by
installing the apt-transport-https package:
sudo apt-get install apt-transport-https
Then add the key of OBiBa’s repository to trusted keys by running the following commands:
wget -q -O - https://pkg.obiba.org/obiba.org.key | sudo apt-key add -
and add OBiBa Debian repository to your repositories list:
echo 'deb https://pkg.obiba.org stable/' | sudo tee
/etc/apt/sources.list.d/obiba.list
Finally update the package list and install Opal server:
sudo apt-get update
sudo apt-get -y install opal
During this step you will be asked to set a password, which you will need to login as administrator
into Opal's web interface.
2.4
Installation of R server
Although Debian provides R from it's default repository, it is not the latest one. This will be fixed
by adding one more external repository.
With the following command you will install the repository’s key:
sudo apt-key adv --keyserver keys.gnupg.net --recv-key 381BA480
Some people have difficulties using this approach because of firewall blocked port 11371. In this
case you may to try the alternative approach:
gpg --keyserver hkp://keys.gnupg.net:80 --recv 381BA480
gpg --export 381BA480 | apt-key add -
And finally add the repository to the list:
echo 'deb https://cran.uni-muenster.de/bin/linux/debian jessie-cran3/' |
sudo tee /etc/apt/sources.list.d/cran.list
Update package list and install R with all available R packages via:
sudo apt-get update
sudo apt-get -y install r-cran*
Before installing the R server some utilities and libraries needs to be installed too. This allows
building additional R packages from source code:
sudo apt-get install -y gfortran g++ libssl-dev libcairo-dev
Then the R server installation is performed using the following commands:
sudo apt-get install -y opal-rserver
After the R server is installed one additional R package is still be required for administration of R
server via Opal. For this purpose it is necessary to start R terminal as root:
sudo R
and install the 'opaladmin' package.
install.packages('opaladmin', repos=c(getOption('repos'),
'http://cran.obiba.org'), dependencies=TRUE)
It is possible to check the installation result with:
is.element("opaladmin",installed.packages()[,1])
If 'opaladmin' installation was successful, you will see the output:
[1] TRUE
Finish R session with
q()
and restart Opal for establishing connection to R server:
sudo service opal restart
2.5
Final configuration
Now Opal is ready for the first Login. Opal’s administrative web interface can be accessed with any
modern web browser by addressing:
https://<host>:8443
Before you can login you will get a security warning, because the default certificate is self-signed
and created for a different host name. It is recommended to replace Opal's default certificate by a
valid one before taking into operation.
But now you can proceed by adding the host to security exceptions.
The first site you will see is the login page. Sign in with 'administrator' as user name and your opal
administrator password (see chapter 2.3).
Add the databases which were configured in chapter 2.2.
The first one is the identifiers database. In the 'Identifiers Database' section, click on 'Register' and
select the 'SQL' database type.
Enter information for the database opal_ids and save the settings.
Upon successful configuration a notification message in blue box pops up.
Repeat the same for the section 'Data Databases' by adding opal_data database.
As previously a blue notification box appears when succeeded.
Click on 'Continue to main site' to continue.
Finally the DataSHIELD packages have to be installed. Change to Administration page by clicking
on 'Administration' in the top bar.
Click on 'DataSHIELD' for changing to DataSHIELD section.
Click on 'Add Package', choose the option 'Install all DataSHIELD packages' and click 'Install'.
The DataSHIELD packages should appear in the list and the 'Methods' section should also be
populated with entries.