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).
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_HOMEenvironment 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
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.
Troubleshooting¶
If you encounter an issue during the installation and you can’t resolve it, please report it in our R Server Issue Tracker.
Rserve logs can be found in /var/lib/rserver/logs/Rserve.log and might indicate R errors.
Rserve package¶
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')
libgit2/libcurl4-openssl conflicts¶
If a conflict is reported between libgit2-dev and libcurl4-openssl-dev (known issue on Ubuntu 18 (bionic)), add the following PPA:
sudo add-apt-repository ppa:cran/libgit2
And then install the opal-rserver package.