Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation Guide

WeBWorKiR Installation Guide

The audience for this guide are system administrators who want to set up R integration in WeBWorK. We assume that you already have, or know how to set up, a basic WeBWorK server. If not, please see the release notes on the WeBWorK wiki and the guide to installing WeBWorK on an Ubuntu server. You may also find Jason Aubrey's ww_install installation script useful.

Installation

After you have a working WeBWorK server, there are three distinct steps that need to happen:

set up the R server
install the Perl module for the Perl-R bridge
configure WeBWorK to use this module in PG

Set up the R server

Your R server (which can be on the same server as WeBWorK, but in a real-world scenario will more likely run on its own hardware/VM), is quite easy to set up:

install R following OS-specific instructions on the project homepage.
install the Rserve server, which allows remote clients to execute R code on the Rserve's server and returns the execution's result in response. The easiest way is to run (as an administrative user) Rscript -e 'install.packages("Rserve", repo="http://cran.rstudio.com")'. Note that this package includes a C source that needs to be compiled, so you have to have the basic developer tools present on the server.
run the Rserve service as appropriate to your system. The command you need to run is "R CMD Rserve". This will start the Rserve daemon which will listen on port 6311. The daemon only accepts connections from the localhost; if you run WebWork and Rserve on separate servers, read the final section of this page for additional configuration steps for your system.

Install the Perl-R bridge

Perl module Statistics::R::IO implements Rserve's communication protocol in Perl and provides translation from R data structures to Perl's. It is available on CPAN and can be installed in the standard manner for Perl modules, e.g., by running (as an admin user) cpan Statistics::R::IO.

Configure Webwork to use the Perl-R bridge in PG

Once the Perl module RserveClient is installed, you can make its functionality available in webwork problems by installing the RserveClient.pl macro and adding the module to the list of modules preloaded by WeBWorK. We use "${WW_PREFIX}" to indicate the directory where WeBWorK is installed. (This directory will, for instance, contain subdirectories "webwork2" and "pg"; a typical choice is "/opt/webwork", but a different one may be used on your system.)

No need to install RserveClient.pl as it is included in the official OPL.install RserveClient.pl macro into "$WW_PREFIX/pg/macros":

wget -q -O ${WW_PREFIX}/pg/macros/RserveClient.pl \ https://raw.githubusercontent.com/cubranic/Statistics-R-IO/release/extras/WebWork/RserveClient.pl

perhaps a better solution, but depending on having the Perl module File::ShareDir, ensures that the RserveClient.pl macro matches the version of Statistics::R::IO that you have installed:

cp "`perl -MFile::ShareDir -e 'print File::ShareDir::dist_file(\"Statistics-R-IO\", \"WebWork/RserveClient.pl\")'`" \ ${WW_PREFIX}/pg/macros/RserveClient.pl

add the RserveClient module(s) to the list of modules preloaded by WeBWorK, so that it is available to the RserveClient.pl macro. You can do this by modifying "${WW_PREFIX}/webwork2/conf/defaults.conf", but since it's a local configuration, you should put it in localOverrides.conf:

cat >> ${WW_PREFIX}/webwork2/conf/localOverrides.conf <<'EOF'
push @{$pg{modules}},
   [qw( Statistics::R::IO::Rserve )],
   [qw( Statistics::R::IO::ParserState )],
   [qw( Statistics::R::REXP::Character )],
   [qw( Statistics::R::REXP::Double )],
   [qw( Statistics::R::REXP::Environment )],
   [qw( Statistics::R::REXP::GlobalEnvironment )],
   [qw( Statistics::R::REXP::Integer )],
   [qw( Statistics::R::REXP::Language )],
   [qw( Statistics::R::REXP::List )],
   [qw( Statistics::R::REXP::Logical )],
   [qw( Statistics::R::REXP::Null )],
   [qw( Statistics::R::REXP::Raw )],
   [qw( Statistics::R::REXP::Symbol )],
   [qw( Statistics::R::REXP::Unknown )],
   [qw( Statistics::R::REXP::Vector )],
   [qw( Statistics::R::REXP )],
   [qw( IO::File )],
   [qw( IO::Handle )];
$pg{specialPGEnvironmentVars}{Rserve} = {host => "localhost"};

1;
EOF

https://github.com/openwebwork/webwork2/pull/700/files

[qw(Rserve Class::Tiny IO::Handle)]

Additional configuration when WeBWorK and R are on separate hosts

If you run WeBWorK and R on separate hosts, you can either set up a tunnel to forward port 6311 from WeBWorK to R's host, or do the following:

set up Rserve to listen on all network interfaces, not just localhost by adding a line "remote enable" to file "/etc/Rserv.conf":
```
cat <'EOF' >> /etc/Rserv.conf
remote enable
EOF
```
use the correct host name (instead of "localhost") in the "Rserve host" line of "localOverrides.conf". For example:
```
$pg{specialPGEnvironmentVars}{Rserve} = {host => "www.example.com"};
```

Note that in this case you will also want to set up the Rserve host's firewall to only allow connections from the WeBWorK host(s), or otherwise it will happily execute arbitrary code from any Rserve client anywhere on the internet!