ReviewR is designed to support multiple concurrent users when deployed using Shiny Server. When deployed on a centralized server an instance of ReviewR will be served to each connecting user in distinct R sessions allowing multiple participants to simultaneously connect to patient data and submit chart abstraction information. In server deployments, users will access ReviewR directly through a web browser without requiring a local R installation.
Before deploying ReviewR to your server, you must first configure your environment to securely host Shiny applications. The overall process consists of 5 main components:
Note: This vignette assumes you have access to a server running Ubuntu 18.04.
This guide is not universally applicable to all server environments. It assumes that no prior services have been installed or configured on your server. It is intended for informational purposes only. We take no responsibility for suggesting configuration changes that break your operational setup. Please make modifications where necessary to adapt this guide to your specific environment and consult your IT department if applicable or necessary.
Information provided in this vignette has been adapted from other guides that have been listed in the Suggested Reading section below.
Using a domain registrar of your choosing, obtain a domain name for your server. There are a wide variety of registrars that will provide am domain name either for free of charge or for a small annual fee. Once you have obtained a domain name for your server, register your server’s external IP address with your domain registrar of choice. Ideally, this external IP address is static, though services exist to update DNS records for servers with ephemeral IP addresses.
Once you have registered for a domain name and linked your domain with your server’s IP you will be able to access your server with a plain text URL, rather than by a IP address. Additionally, a domain is required to encrypt connections to/from your server. This is because certificate authorities, like Let’s Encrypt, are required to verify ownership of domains before security certificates can be issued. These certificates are what allows traffic to be SSL encrypted between clients and your server via the https standard. By registering your server’s IP address with a domain registrar and associating it with a domain name, you are verifying that you own the site and take all responsibility for its functions.
Before installing Shiny Server, it is necessary to install a few prerequisites to your server. To begin, SSH into your server and perform the following steps:
gdebi, which is an operating system package
that is used to install Shiny Server, and additional dependencies:Now that all prerequisites have been satisfied, download and install Shiny Server to your system:
wget https://download3.rstudio.org/ubuntu-18.04/x86_64/shiny-server-1.5.20.1002-amd64.deb
sudo gdebi shiny-server-1.5.20.1002-amd64.debAt this point, you will have a bare bones basic Shiny Server
Installation. If you would like to verify that Shiny has installed
correctly, you may attempt a connection from a different machine on the
same network by visiting: your.server.ip_address:3838
Read on to learn how to secure this connection.
At this stage, your Server is being hosted on port 3838 of your machine. In order to allow users to access this server via the domain that was acquired in the first portion of this guide, we will need to install and configure a reverse proxy which will direct clients securely to applications hosted on your shiny server. NGINX, an open source web server and reverse proxy will be used for the purposes of this guide.
To begin, install NGINX on your server:
You can verify this installation by visiting
your.server.ip_address from a different machine on the same
network. You should see a ’Welcome to nginx!” message if all was
successful.
Depending on where your server is hosted, you may have to allow access to the server’s IP address on ports 80 and 443. Firewall configuration is outside of the scope of this guide.
Next, we need to configure NGINX to proxy traffic from web clients to
the Shiny Server, where Shiny applications will be hosted. To do this,
we’ll need to add a server block to NGINX with information about our
Shiny Server. NGINX server blocks live in
/etc/nginx/sites-available/. To initialize a server block
for our shiny server, issue the following command:
## substitute nano for your preferred text editor: emacs, jed, joe, pico, sandy, vi, vim, etc.
sudo nano /etc/nginx/sites-available/shinyModify the following server block code by replacing
your.shiny.server.url with the domain name that you
obtained in the Obtain a Domain section
of this guide. Then, copy this text into the file that you are
editing.
server {
server_name your.shiny.server.url;
location / {
proxy_pass http://localhost:3838;
proxy_redirect / $scheme://$http_host/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 20d;
proxy_buffering off;
}Save and exit the file. Verify that the has been created successfully by running:
A file called “shiny” should be among the files that is returned.
Next, we need to enable the server block that we just created. With
NGINX, this is accomplished by symlinking the server block to the
/etc/nginx/sites-enabled folder. Run:
At this point, your Shiny Server should be accessible at
http://your.shiny.server.url . If the Shiny Server is not
immediately available at your domain after completing all of the steps
to this point, you may have to restart NGINX;
sudo systemctl reload nginx
Continue to the next section to secure your server with Let’s Encrypt.
To begin, we will install the Certbot software on our server. This software makes it easy to secure our domain, by automatically verifying ownership, downloading and installing a Let’s Encrypt certificate, automatically configuring nginx to use the certificate, and renewing the certificate before it expires. You want this software, trust me. To install Certbot, we’ll need to add a software repository to our system. This will be accomplished by running:
Next, we’ll need to update our server’s package list, and install the Certbot application for our nginx configuration:
As we have already configured a server block for NGINX in the
previous section, we are ready to run the Certbot software to secure our
domain. Run the following code block, substituting
your.shiny.server.url with the domain that you configured
in the nginx server block for shiny server:
If this is your first time running Certbot, you will be prompted to enter an email address and agree to the terms of service. After doing so, Certbot will initiate a connection with the Let’s Encrypt server and then begin testing your server to verify that you control the domain you’re requesting a certificate for. Certbot will then ask you whether or not you’d like to redirect all HTTP traffic to HTTPS traffic. It is highly recommended to do so. Please select the option for ‘Redirect’, which will ensure that users are only capable of accessing your site via secure HTTPS.
Congratulations, your Shiny Server is now secured and ready to begin hosting Shiny Applications. Continue to the next section to learn how to deploy ReviewR to your Shiny Server.
Install the ReviewR package as a root user in order to ensure your system R package library has all of the required dependencies
From a bash terminal, run:
This will open an interactive R console as a root user
From the R console that opens, run:
Continuing as the root user, fork the ReviewR repository into the
Shiny Server directory (/srv/shiny-server) with the
usethis package. Using the same R console
from above:
# install.packages('usethis')
usethis::create_from_github(repo_spec = 'thewileylab/ReviewR', destdir = '/srv/shiny-server')This step will fork the most recent version of the ReviewR
package from GitHub which includes additional files and development
tools not built directly into the package. This includes an
app.R file which Shiny Server will need to deploy ReviewR.
By default, Shiny Server will host all applications that are placed in
/srv/shiny-server
That’s it! ReviewR can now be accessed from your browser at:
https://your.shiny.server.url/ReviewR