Docker image for an Intro to R training environment using RStudio Workbench (formerly called RStudio Server Pro). This image is based on rstudio/rstudio-workbench. It automatically generates a configurable number (up to 999) of training accounts, which can be useful for Intro to R courses such as Intro to R for Clinical Data at the R/Medicine 2022 Virtual Conference.
Note: To use this Docker image, you need an active RStudio Workbench license.
The Dockerfile
extends rstudio/rstudio-workbench by adding:
libxml2-dev
, vim
, and git
packagestidyverse
, rmarkdown
, and devtools
R packagesIn addition, the startup script accomplishes the following:
exercises
and solutions
.train001
, train002
, ... or rmed001
, rmed002
, ...
docker run
is invoked.exercises
and solutions
folders are copied.docker build -t rwb-train .
The following example will start an RStudio Workbench instance with shiny
, flexdashboard
, and plotly
packages from CRAN, as well as the rstudio/DT
package from GitHub, installed globally. One hundred users will be created, named rmed001
, rmed002
, ... rmed100
. Each user's home directory will have a copy of the exercises
and solutions
folders from the skadauke/intro-to-r-for-clinical-data-rmed2022
GitHub repository, as well as a folder titled backup
which contains another copy of the exercises
folder (This comes in handy if the learner accidentally deletes or otherwise changes an exercise file).
Note: RStudio Workbench does not currently work on Apple Silicon.
# Replace with valid license
export RSP_LICENSE=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
docker run --privileged -it \
-p 8787:8787 \
-e USER_PREFIX=rmed \
-e N_USERS=100 \
-e PW_SEED=12345 \
-e GH_REPO=https://github.com/skadauke/intro-to-r-for-clinical-data-rmed2022 \
-e R_PACKAGES=shiny,flexdashboard,plotly \
-e R_PACKAGES_GH=rstudio/DT \
-e RSP_LICENSE=$RSP_LICENSE \
-v "$PWD/server-pro/conf/":/etc/rstudio \
rwb-train
Open http://localhost:8787
to access RStudio Workbench.
The create_users_table.R
script is used by the startup script to generate users and can be invoked manually to create a list of usernames and passwords for a specific random seed.
Usage: ./create_users_table.R <user_prefix> <n_users> <pw_seed> <filename>
For example, to create the list of 100 users with the same seed as in the docker run
command above, type:
./create_users_table.R train 100 12345 users.txt
This generates the file users.txt
which is a tab delimited file listing usernames and passwords.
The following instructions explain how to set up an RWB training instance on AWS for teaching. They assume some familiarity with AWS, including the EC2 and Route 53 services, as well as the Linux command line.
Dockerfile
. Substitute your Docker Hub username for <your_username>
):docker build <your_username>/rwb-train
docker push <your_username>/rwb-train
Create an EC2 instance with the following properties:
t2.micro
machine (1 GB, 1 core) works well..pem
file to ~/.ssh/
of your local machine. Change the permissions to be readable only by root chmod 400 my-key-file.pem
.Note the Public IPv4 address of the machine.
From within EC2, allocate an Elastic IP and associate it with your instance. This will avoid the hassle of changing the IP address in DNS records every time you shut down and restart your server.
Register a domain name for your server using Route 53 - only needed if you don't have a domain name yet. One way to do this is using AWS' Route 53 service.
Note: It may take up to 3 days for the domain registration to be processed and for the DNS record to propagate through the internet.
Create a hosted zone in Route 53 for your domain name. (If you just registered the domain name, Route 53 will have created a hosted zone for you). Within the hosted zone, create a new DNS record (record type A) that points the host name to the IP of your server. Be sure to use the Elastic IP for the IP. For more information, see here.
Important: if you created a hosted zone for a domain that you had previously registered, you must change the name servers on the domain registration to match the authoritative domain servers in the NS record of the hosted zone. In Route 53, go to registered domains -> click on your domain -> click Add or edit name servers.
In the hosted zone, change the TTL of the NS record to 60 seconds. Note: it may take a long time for the DNS to work. To make sure there aren't any issues, see this page for troubleshooting advice.
Log into the machine, substituting <path-to-your-pem-file>
for the path to the .pem
key file, and <your_server>
for either the elastic IP address or the domain name of the server.
ssh -i <path-to-your-pem-file> ubuntu@<your_server>
Enter "yes" if asked if you want to connect. If you get a warning about an unprotected private key file, change permissions to user read-only by running chmod 0400 <path-to-your-pem-file>
.
Note: as an easier alternative to SSH, you may use EC2 Connect. From the EC2 dashboard, click Connect.
sudo apt update &&
sudo apt upgrade &&
sudo ufw allow OpenSSH &&
sudo ufw enable
sudo apt install nginx &&
sudo ufw allow 'Nginx Full' &&
sudo systemctl start nginx &&
sudo systemctl enable nginx
http://<your_server>
.The nginx splash page should show.
Substitute <your_domain>
with the domain name you registered:
sudo snap install --classic certbot &&
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx -d <your_domain>
Enter your email when prompted.
Use your browser to connects to http://<your_server>
. Note that you got redirected to a secure HTTPS page. A lock should appear in your browser to the right of the URL to confirm that the TLS/SSL certificate is valid.
sudo apt update &&
sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release &&
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg &&
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update &&
sudo apt install docker-ce docker-ce-cli containerd.io
rwb-train
container. Substitute <license>
with your RSP license.
You should modify the following options to the docker run
command:
USER_PREFIX
: the left side of the name you want for your users to have, e.g. rmed
. GH_REPO
: The GitHub repository with the training materials (exercises, solutions)R_PACKAGES
: Additional R packages you would like to installN_USERS
: The number of user accounts you want to create. Note: the first 10 user accounts (001-010) should be reserved for instructors - these accounts will have sudo
privileges inside the container, which can be useful for troubleshooting.PW_SEED
: The random seed for generating user passwords. You must supply this to generate reproducible passwords. sudo docker pull skadauke/rwb-train
export RSP_LICENSE=<license>
sudo docker run --privileged -it \
--detach-keys "ctrl-a" \
--restart unless-stopped \
-p 8787:8787 -p 5559:5559 \
-e USER_PREFIX=rmed \
-e GH_REPO=https://github.com/skadauke/intro-to-r-for-clinical-data-rmed2022 \
-e R_PACKAGES=shiny,flexdashboard,plotly,DT,markdown \
-e N_USERS=100 \
-e PW_SEED=12345 \
-e RSP_LICENSE=$RSP_LICENSE \
-v "$PWD/server-pro/conf/":/etc/rstudio \
skadauke/rwb-train
Ctrl+A
to detach the image. This will allow you to take back control of the console. The container will continue to run in the background.
Scroll up in your terminal to find them. You will need to hand these out to participants.
Below, substitute <my_hostname>
with the domain name of your host.
Inside the /etc/nginx/sites-available/default
file, replace the following lines:
location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
try_files $uri $uri/ =404;
}
With the following:
location / {
proxy_pass http://localhost:8787;
proxy_redirect http://localhost:8787/ $scheme://$http_host/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 20d;
}
Add the following lines right after http {
in /etc/nginx/nginx.conf
:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server_names_hash_bucket_size 64;
sudo nginx -t &&
sudo systemctl restart nginx
To verify that everything worked, navigate to http://<your_server>
. To the left of the URL, a lock icon should appear to indicate that a secure HTTPS connection is being used. The RStudio Workbench login should show up. Make sure you can log in using the first user (e.g., rmed001
).
Note: While you are working on setting up the EC2 instance, you may want to stop it to save money. If you associated an elastic IP, starting it back up should restore a fully functional environment.
docker run
command (see above for examples).# The following commands stop and remove *all* docker containers - proceed with caution!
sudo docker kill $(sudo docker ps -q) &&
sudo docker rm $(sudo docker ps -a -q)
To stop getting charged, you will want to make sure remove all of the following after you are done:
Manually deactivating the license: http://apps.rstudio.com/deactivate-license/
a1.4xlarge
instance which costs $0.408 per hour, which comes out to $9.79 per day. To save money, you can first create a small testing instance and then, the day prior to the workshop, replace it with a beefier instance. For multi-day workshops, you can also stop the instance at the end of the day and restart it at the beginning of the next day.