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).
Server Hardware Requirements¶
|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.
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
- 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')
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.
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:
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.
The R Server Admin application can be launched from the command line.
||yes||Path to the R Server “home” directory.|
||no||Options for the Java Virtual Machine. For example: -Xmx4096m -XX:MaxPermSize=256m|
To change the defaults update:
Execute the command line (bin directory is in your execution PATH)):
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.
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
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')
R Server Admin package has two configuration files: one for the R server controller and one for the R serv itself.
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.
||R server controller port (default is 6312).|
||R executable path, required to launch the R server.|
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.