This topic explains how administrators can set up communication between LabKey Server and an RStudio instance packaged inside a Docker image. As part of the configuration, we recommend that you allow Docker, not LabKey Server, to manage the RStudio data using Docker Volumes. This avoids a number of issues with file sharing, permissions, path mapping, and security, making setup much easier.
Install Docker
Docker is available for Windows 10, MacOS, and a variety of Linux platforms. The Docker installation documentation is available here:
Follow the instructions for installation on your platform.
- On Windows, we recommend "Docker Desktop for Windows".
- On OSX, "Docker Toolbox" is known to work.
Test your Docker installation using an example container, for example: 'docker run hello-world' (
https://docs.docker.com/engine/tutorials/dockerizing/)
Connect Using UNIX SOCKET or TCP
Depending on your platform and server mode, you have several connection options:
Connect using UNIX SOCKET
On Mac and Linux, you can connect directly via the docker socket, usually at
unix:///var/run/docker.sock
Connect using TCP - Developer mode
If you are developing or testing locally, you can skip setting up TLS if both of the following are true:
- Use port 2375 instead of 2376
- Run with devmode=true
Otherwise a secure connection is required, as described in the next section, whether the docker server is local or remote.
Connect using TCP and TLS - Production mode
In production you must set up TLS if you are connecting over the network, and you may also want to set it up for certain kinds of development. Set up TLS following these steps:
- See https://docs.docker.com/engine/security/https/
- An example TLS and certificate configuration for LabKey Server is available in this companion topic:
- After certificates are set up, find the values of the following environment variables. You will use these values in the Configure Docker step below. (On Linux run 'env | grep DOCKER'.)
- DOCKER_CERT_PATH
- DOCKER_HOST
- On an Ubuntu system modify the "/etc/default/docker" file to include the following:
DOCKER_TLS_VERIFY=1
DOCKER_HOST=tcp://$HOST:2376
DOCKER_CERT_PATH=<YOUR_CERT_PATH>
DOCKER_OPTS="--dns 8.8.8.8 --tlsverify --tlscacert=$DOCKER_CERT_PATH/ca.pem --tlscert=$DOCKER_CERT_PATH/server-cert.pem --tlskey=$DOCKER_CERT_PATH/server-key.pem -H=0.0.0.0:2376"
Build the LabKey/RStudio Image
- Clone the docker-rstudio repository from github: https://github.com/LabKey/docker-rstudio (This is not a module and should not be cloned into your LabKey server enlistment.)
- cd to the rstudio-base directory:
cd docker-rstudio/images/labkey/rstudio-base
- Build the image from the source files.
- Test by running the following:
docker run labkey/rstudio-base
You may need to provide a password (generate a Session Key to use as a password) to perform this test, but note that this test is simulating how RStudio will be run from LabKey and you do not need to leave this container running or use a persistent password or API key.
docker run -e PASSWORD=<Your_Session_Key> -p 8787:8787 labkey/rstudio-base
- Check console output for errors.
- Ctrl-C to get to return to the command prompt once you see the 'done' message.
- Stop this test container by running:
docker stop labkey/rstudio-base
Enable Session Keys
Your server must be configured to accept session keys in order for token authentication to RStudio to work. One time access codes will be generated for you.
You do not need to generate any session keys yourself to use RStudio.
Check Base Server URL
- Go to (Admin) > Site > Admin Console.
- Under Configuration, click Site Settings.
- The Base Server URL cannot be localhost. For a local development machine, you can substitute your machine's actual IP address (obtain via ipconfig) in this entry.
- Note that you may have to log out of "localhost" and log in to the actual IP address to use RStudio from a local server.
Configure Docker
For details, see
Configure Docker Host.
- If you have successfully created the Docker image, it will be listed under Docker Volumes.
- When configuring Docker for RStudio, you can skip the prerequisite check for user home directories.
- The configuration page will show a list of existing volumes and corresponding user emails. The email field is blank if the volume doesn't correspond to an existing user.
Configure RStudio
- Go to (Admin) > Site > Admin Console.
- Under Premium Features click RStudio Settings.
- Select Use Docker Based RStudio.
Configure the fields as appropriate for your environment, then click
Save.
- Image Configuration
- Docker Image Name: Enter the Docker image name to use for RStudio. Default is 'labkey/rstudio', which includes Rlabkey.
- Port: Enter port the RStudio Server will listen on inside Docker. Default is 8787.
- Mount Volume: Enter the volume inside the Docker container to mount as the RStudio user's home directory. Default is '/home/rstudio'.
- Host library directory (read-only): Optional read-only mount point at /usr/lib/R/library
- Additional mount: host/container directories (read-only): Optional read-only mount points
- User for Containers: Optional user to use for running containers inside docker
- AppArmor Profile: If needed
- Local IP address for LabKey Server: Set to the IP address of the LabKey Server from within your docker container. This may be left blank if the normal DNS lookup works.
- Resource Configuration: Customize defaults if needed.
- Max User Count: Default is 10
- Stop Container Timeouts (in hours)": Default is 1.0. Click to Stop Now.
- Delete Container Timeouts (in hours)": Default is 120.0. Click to Delete Now.
- RStudio initialization configuration:
Click
Save when finished. A button to
Restore Defaults is also available.
Enable RStudio in Folders
The modules
docker and
rstudio must be enabled in each folder where you want RStudio to be available. Select
(Admin) > Folder > Management, select the
Folder Type tab and make sure both modules are checked in the right column. Click
Update Folder to save any changes.
Once RStudio is enabled, you can use the instructions in these topics to edit reports and export data:
Related Topics
