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://cran.rstudio.com', 'http://cran.obiba.org'), dependencies=TRUE, lib='/usr/local/lib/R/site-library')

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://cran.rstudio.com', 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.