As an alternative to installing a local instance of R, or using an Rserve server, LabKey Server can make use of an R engine inside a Docker image.
Multiple Docker-based R engines can be configured, each pointing to different Docker images, each of which may have different versions of R and packages installed.
Docker-based R engines are good candidates for "
sandboxed" R engines.
To set up LabKey Server to use Docker-based R engines, complete the following steps:
- Install Docker
- Make a Docker Image with R Included
- Configure LabKey Server to Use the R Docker Engine
Install Docker
Install Docker as appropriate for your operating system. More details are available in the topic:
For development/testing purposes, on a Windows machine, you can use a non-secure connection in your Docker Settings. Under General, place a checkmark next to
Expose daemon on tcp://localhost:2375. Do
not do this on a production server, as this is not a secure configuration. Only appropriate for local development and testing.
Make and Start a Docker Image with R Included
LabKey provides two template images to start from. One template is for building a Dockerized R engine using the latest released version of R. The other template is for building an older version of R.
- To create a Docker image with the latest available version of R, see the following topic. Since this always uses the latest R version, the actual R version will differ based on the latest R version available at the time the build command is run.
- To create a Docker image with a specific version of R, see the topic below. Note that this template set the default R version to 3.4.2, but this can be changed to any R version in the make files. Note that when using this image, R packages are installed from a CRAN snapshot so that package versions are correct for the R version.
- Also see this topic for general instructions on building Docker R images:
Start the Docker Image
When the docker image build process finishes, look for the name of your image in the console, for example:
Successfully tagged labkey/rsandbox-base:3.5.1
Start the image:
docker run labkey/rsandbox-base:3.5.1
Configure LabKey Server to Use the Docker R Engine
Step 1: Set the
Base Server URL to something other than localhost:8080. For details, see
Site Settings. Example value "http://my.server.com". You can also use the full IP address of a localhost machine if needed.
Step 2: Configure a Docker host as described here:
Configure Docker HostStep 3: Enable the sandboxing feature flag:
On your LabKey Server, first confirm that the sandboxing feature flag is enabled:
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Experimental Features.
- Under R Docker Sandbox, click Enable.
- Click Admin Console near the top of the page, then click Views and Scripting (also under Configuration) for the next step.
Step 4: Add the New Docker R Engine
On the
Admin Console > Views and Scripting page, select
Add > New Docker R Engine.
- In the Edit Engine Configuration dialog, enter the Docker Image Name (shown here as "labkey/rsandbox"). If you are using RStudio Integration via Docker, this name will be "labkey/rstudio-base".
- The Mount Paths let you (1) map in-container paths to host machine paths and (2) to write script outputs the mapped path on the host machine. For example, the following settings will write the script.R and script.Rout generated files to your host file system at C:\scripts\Rreports:
Mount (rw): host directory: C:\scripts\Rreports
Mount (rw): container directory: /Users/someuser/cache
- Mount (rw) paths refer to Read-Write directories, Mount (ro) refer to Read-Only paths.
- Extra Variables: Additional environment variables to be passed in when running a container.
- Usage example: 'USERID=1000,USER=rstudio' would be converted into '-e USERID=1000 -e USER=rstudio' for a docker run command.
- A special variable 'DETACH=TRUE' will force the container to run in detached mode, with '--detach'.
- Site Default refers to the default sandboxed R engine.
- If you have only one sandboxed R engine, this cannot be unchecked. If you have more than one sandboxed R engine, you can choose one of them to be the Site Default.
- Enabled: Check to enable this configuration. You can define multiple configurations and selectively enable each.
Click
Submit to save your configuration.
Related Topics
