Set Up RStudio Workbench

 2024-04-15
This topic is under construction for the 24.3 (March 2024) release of LabKey Server with embedded Tomcat 10. For the previous documentation, click here.

Premium Feature — This feature supports RStudio, which is part of the Professional and Enterprise Editions of LabKey Server. Learn more or contact LabKey.

This topic covers setting up and configuring RStudio Workbench (previously RStudio Server Pro) for use with LabKey Server. These instructions will not work with the RStudio Server Open Source version but only work for RStudio Workbench. RStudio Workbench runs as a separate server, and unlike RStudio, can shared by many simultaneous users. On the machine where RStudio Workbench is running, the R language must also be installed and the Rlabkey package loaded.

Typically the steps on this page would be completed by a system administrator, though not necessarily the LabKey site administrator. Once the steps described here have been completed on the RStudio Workbench machine, the LabKey Server can be configured to connect to RStudio Workbench as described in Connect to RStudio Workbench. Key pieces of information from this setup must be communicated to the LabKey admin.

Environment Setup

AWS Notes

  1. If you're setting this server up in AWS, you will want to set it up in a public subnet in the same VPC as the destination server. It will need a public-facing IP/EIP.
  2. For AWS, the following ports need to be open, inbound and outbound, for this install to work in AWS. Set your security group/NACLs accordingly:
    • 80
    • 443
    • 1080 (license server)
    • 8787 (initial connection)
    • 1024-65535 (license server)

Linux and Ubuntu Setup

If your RStudio Workbench host machine is running an OS other than Linux/Ubuntu, you can configure a VM to provide a local Linux environment in which you can run Ubuntu. If your host is Linux running Ubuntu, you can skip this section.

Steps to set up Ubuntu on a non Linux host OS:

  1. VM: Use Virtual Box to set up a local Linux environment.
  2. Linux: Install Linux OS in that VM
  3. Ubuntu: Download and install the latest Ubuntu (version 12.04 or higher is required) in the VM.
  4. Configure VM network so that VM has an IP and can be accessed by the host. For example: VM > Settings > Network > Attached To > Bridged Adapter

R Language Setup (for Ubuntu)

Use the following steps to set up R for Ubuntu. For other versions of linux, follow the instructions here instead: http://docs.rstudio.com/ide/server-pro/index.html#installation

1. Configure CRAN Repository. Add the following entry to your /etc/apt/sources.list file, substituting the correct name for your Ubuntu version where this example uses 'xenial' (the name for 16.x): 

deb https://cran.cnr.berkeley.edu/bin/linux/ubuntu xenial/

If you are not sure what name your Ubuntu version is using, you can find it in other lines of the sources.list file.

Linux Tip: to open a system file in linux for editing, use: 
$ gksudo gedit  /etc/apt/sources.list
To add edit permission to a file: 
$ chmod 777 /etc/apt/sources.list

2. Install latest version of R 

apt-get update
apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E084DAB9
sudo apt-get install r-base

3. Install Rlabkey and other R packages

  • If a library is to be used by RStudio as a system library (instead of a user library), run with 'lib' set as shown here: 
    $ sudo R
    > install.packages("Rlabkey", lib="/usr/local/lib/R/site-library")
    > q()
  • If a library has dependencies: 
    > install.packages("package", lib="/usr/local/lib/R/site-library", dependencies=TRUE)
    > q()
Trouble installing Rlabkey on Linux? Try installing dependencies explicitly: 
> sudo apt-get install libssl-dev
> sudo apt-get install libcurl4-openssl-dev

Install RStudio Workbench

1. Download and install RStudio Workbench as instructed when you purchased it. For demo purposes, you can use the free 45 day trial license and download from the RStudio download page. 

$ sudo apt-get install gdebi-core
wget https://download2.rstudio.org/rstudio-server-pro-1.1.447-amd64.deb
(nb: this URL may not be current. Check the RStudio download page for latest version)

gdebi rstudio-server-pro-1.1.447-amd64.deb (substitute current version)

2. Activation: (Optional)

$ sudo rstudio-server license-manager activate ACTIVATION_KEY

This function requires high ports to be world-accessible. If this command fails, check your security groups or NACLs; if this fails with a timeout, check them first.

3. Verify RStudio Workbench Installation

  1. Create a ubuntu user: 
    useradd -m -s /bin/bash username
    passwd username
  2. Get Ubuntu’s ip address by: 
    $ ifconfig
  3. In VM browser, go to localhost:8787, or ip:8787
  4. You should be on the RStudio Workbench login page, login using your ubuntu login
4. Verify accessing RStudio Workbench from the host machine

In the host machine’s browser, go to your VMs IP address. Depending on how you configured your license, it might look something like "http://ubuntuVmIPAddress:8787". You should see the RStudio login page and being able to log in.

Troubleshoot: did you configure VM to use Bridged Adapter?

5. Create a Route 53 DNS name for the server. You will need this for the next steps.

Configure RStudio Workbench Proxy

The RStudio Workbench administrator must enable proxy authentication on RStudio Workbench to use LabKey Server as the authenticator. The following steps will configure the proxy. See below for the details that must then be used when configuring LabKey Server to use this proxy. Note that this option is not supported for RStudio Server Open source and only works for RStudio Workbench.

1. You will need to create an SSL cert:

  1. openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 3650 -out certificate.pem
  2. Copy the key.pem file to /etc/ssl/private/
  3. Copy the certificate.pem file to /etc/ssl/certs
  4. Edit /etc/rstudio/rstudio-server.conf and add the following lines: 
    ssl-enabled=1
    ssl-certificate=/etc/ssl/certs/cert.pem
    ssl-certificate-key=/etc/ssl/private/key.pem
  5. rstudio-server stop
  6. rstudio-server start
2. Use LabKey Server as proxy authenticator for RStudio Workbench by adding the following lines to /etc/rstudio/rserver.conf, supplying your own server name: 
auth-proxy=1
auth-proxy-sign-in-url=https://YOUR_SERVER_NAME/rstudio-startPro.view?method=LAUNCH

3. Restart RStudio Workbench so that these configuration changes are effective by running 

$sudo rstudio-server restart

4. Follow the instructions here for downloading the cert: https://stackoverflow.com/questions/21076179/pkix-path-building-failed-and-unable-to-find-valid-certification-path-to-requ

5. Upload the saved cert to the destination server

6. On the destination LabKey Server (nb: this will require restarting the LabKey instance):

  1. Log in.
  2. sudo su -
  3. keytool -import -keystore /usr/lib/jvm/jdk1.8.0_151/jre/lib/security/cacerts -alias <RStudio hostname, but not the FQDN> -file <whatever you named the saved cert>.crt (nb: you will be prompted for a password; ask Ops for it)
  4. service tomcat_lk restart
7. Verify Proxy redirect Go to the RStudio Workbench url to verify the page redirects to LabKey. Note: Once SSL is enabled, 8787 no longer works.

8. Customize Security Token

Define a custom security token for the proxy. This will be used to indicate the authenticated user when LabKey Server connects to RStudio Workbench. For example, to define the default 'X-RStudio-Username' token: 

$sudo sh -c "echo 'X-RStudio-Username' > /etc/rstudio/secure-proxy-user-header"
$sudo chmod 0600 /etc/rstudio/secure-proxy-user-header

Information to Pass to LabKey Administrator

To configure LabKey Server to connect to RStudio Workbench, the admin will need:

(Optional) Add RStudio Workbench Users

LabKey users are mapped to RStudio users by removing the configured "email suffix". For example: LabKey user XYZ@email.com is mapped to RStudio user name XYZ

Adding RStudio Workbench Users

RStudio Workbench uses Linux’s PAM authentication so any users accounts configured for Linux will be able to access RStudio Workbench. Users can be added for RStudio by the adduser Linux command.

The following commands add a user “rstudio1” to Linux (and hence RStudio Workbench).

$ sudo useradd -m -d /home/rstudio1 rstudio1
$ sudo passwd rstudio1

IMPORTANT: Each user must have a home directory associated with them otherwise they won’t be able to access RStudio since RStudio works on this home directory.

Verify Access

Verify access to RStudio Workbench for the newly added user:

Go to ip:8787, enter user and pw for the newly created user, verify the user can be logged in to RStudio successfully.

Troubleshoot for permission denied error on login:

  1. Run pamtester to rule out PAM issue 
    $ sudo pamtester --verbose rstudio <username> authenticate acct_mgmt
  2. Try adding the following line to /etc/sssd/sssd.conf (you may need to install sssd): 
    ad_gpo_map_service = +rstudio
  3. Did you create the user with a specified home directory?
  4. Make sure you didn’t configure the RStudio Workbench server to limit user access by user group (the default is to allow all; check /etc/rstudio/rserver.conf), or if so make sure your user is added to an allowed group.

Troubleshooting

After making any change to the RStudio Workbench config, always run the following for the change to take effect: 

$sudo rstudio-server restart

Related Topics