Premium Feature — Available in the Professional and Enterprise Editions of LabKey Server. Learn more or contact LabKey.

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:

  1. Install Docker
  2. Make a Docker Image with R Included
  3. 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.

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 "". 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 Host

Step 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

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all