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:  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.