R Server

Installation

Opal is able to interact with a R server for running statistics analysis and reports.

This guide is about how to install and configure an application called “R Server Admin”. This application is made of a R server controller that does the following;

  • listen to request for starting / stopping the R server,
  • launch / shutdown the R server upon request.

Typical usage is the ability to start / stop a R server from the Opal R Server Administration User Interface. This decoupling of Opal and the R server allows to:

  • run the R server on a different host,
  • run the R server on behalf of a user having limited rights (in particularly, not having access to Opal server files).
../_images/opal-r-server.png

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.

Software Suggested version Download link Usage
Java = 1.8.x Java Oracle downloads Java runtime environment
R >= 3.0.x R downloads Statistical analysis engine

While Java is required by Opal server application, MongoDB/MySQL/R can be installed on another server.

Install

Opal is distributed as a Debian/RPM package and as a zip file. The resulting installation has default configuration that makes Opal ready to be used. Once installation is done, see Configuration instructions.

Debian Package Installation

Opal R Server 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 how to manage the Service.

RPM Package Installation

Opal R Server 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 how to manage the Service.

Zip Distribution Installation

Opal R Server is also available as a Zip file. To install Opal zip distribution, proceed as follows:

  • Download R Server Admin distribution
  • Unzip the R Server Admin distribution. Note that the zip file contains a root directory named rserver-admin-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 a RSERVER_HOME environment variable
  • Install Rserve, a R package that is library that enables the connection with R. This can be done within R by using the CRAN install command from the R console:
install.packages(c('rserve', 'opal', 'tidyverse', 'knitr', 'rmarkdown'), repos=c('http://cloud.r-project.org', 'http://cran.obiba.org'), dependencies=TRUE, lib='/usr/local/lib/R/site-library')

Docker Image Installation

The opal-rserver docker image provided by OBiBa contains a R server (and its controller) with a lot of useful pre-installed system libraries and R packages (tidyverse, Bioconductor, Geospatial libraries etc.).

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-rserver

RPM Package Upgrade

If you installed Opal via the RPM package, you may update it using the command:

yum install opal-rserver

Zip Distribution Upgrade

Follow the Installation of Opal Zip distribution above but make sure you don’t overwrite your opal-home directory.

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 rserver help

The Opal service log files are located in /var/log/opal directory.

Manually

The R Server Admin application can be launched from the command line.

Environment variable Required Description
RSERVER_HOME yes Path to the R Server “home” directory.
JAVA_OPTS no Options for the Java Virtual Machine. For example: -Xmx4096m -XX:MaxPermSize=256m

To change the defaults update: bin/rserver or bin/rserver.bat

Execute the command line (bin directory is in your execution PATH)):

rserver

The R Server Admin server log files are located in RSERVER_HOME/logs directory. If the logs directory does not exist, it will be created by R Server.

Usage

R Server Admin is a REST server and therefore can be queried using the curl tool.

# R Server Admin requests

# status of the R server
curl localhost:6312/rserver

# start R server (ignored if already started)
curl -X PUT localhost:6312/rserver

# stop R server (ignored if already stopped)
curl -X DELETE localhost:6312/rserver

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.

Rserve logs can be found in /var/lib/rserver/logs/Rserve.log and might indicate R errors.

In case the Rserve R binary package does not match the R version, it is possible to update it from the R console (started as root), with the following command:

# install regular package
install.packages('Rserve', repos='http://cloud.r-project.org', lib='/usr/local/lib/R/site-library')

# OR install package from source
install.packages('Rserve', 'http://www.rforge.net/', type='source', lib='/usr/local/lib/R/site-library')

Configuration

R Server Admin package has two configuration files: one for the R server controller and one for the R serv itself.

Controller Configuration

The file RSERVER_HOME/conf/application.properties allows the configuration of the R server controller. This one provides REST web services to start/stop a R server.

Property Description
server.port R server controller port (default is 6312).
r.exec R executable path, required to launch the R server.

Rserve Configuration

The file RSERVER_HOME/conf/Rserv.conf allows the configuration of the core R server. See also the full documentation of the Rserv.conf file.

By default the R server has the following configuration:

  • connection port is 6311,
  • remote connection is disabled,
  • no authentication is required.

If the R server is installed on a different machine as the Opal server, you typically will have to:

  • enable remote connection,
  • enable authentication.

R Session Configuration

When a new R session is started on server side the starting state of this session can be configured using the RSERVER_HOME/conf/Rprofile.R. Any R command (to be executed by the rserver user) can be put in this file.