Running R Shiny Server on NERC

Running R Shiny Server on NERC OpenStack

Setup R Shiny Server using Terraform

Refer to this documentation on using Terraform to set up an R Shiny Server on your NERC OpenStack.

To get started, you will need to clone the repository using:

git clone https://github.com/nerc-project/terraform-nerc-r-shiny.git

Setup R Shiny Server while launching a VM

Within the terraform-nerc-r-shiny repo, it includes the bash script file i.e. install-R-Shiny-<OS>.sh required to setup the R Shiny Server. You can use a custom user-defined bash script based on your selected Image OS while launching an instance.

During the launch, in the "Configuration" tab, you can enter the script in the "CustomizationScript" text area or upload the script file directly.

Which R Shiny Script i.e. install-R-Shiny-<OS>.sh to Choose?

Please use the appropriate bash script file i.e. install-R-Shiny-<OS>.sh based on your operating system (OS):

AlmaLinux → install-R-Shiny-AlmaLinux.sh
CentOS → install-R-Shiny-Centos.sh
Ubuntu → install-R-Shiny-Ubuntu.sh

Running R Shiny Server on NERC OpenShift

We have used the Base Docker image compatible with OpenShift to create an OpenShift Template. Here, we walk through the process of creating a simple R Shiny Server template that bundles all the necessary resources—ConfigMap, Pod, Route, Service, etc.—and then deploy a Shiny application using that template.

Steps to Prepare Your Git Repo with Application Source Code

To get started, fork the rshiny-testapp App in your own Github account.

Very Important Information

As you won't have full access to this repository, we recommend first forking the repository on your own GitHub account. So, you'll need to update all references to https://github.com/nerc-project/rshiny-testapp.git to point to your own forked repository.

To create a fork of the example rshiny-testapp repository:

Go to https://github.com/nerc-project/rshiny-testapp.
Click the "Fork" button to create a fork in your own GitHub account, e.g. "https://github.com/<github_username>/rshiny-testapp".

Clone your forked rshiny-testapp git repository:

git clone <https://github.com/><github_username>/rshiny-testapp.git
cd rshiny-testapp

Shiny Application Source

A ready-to-use sample Shiny application is available within the Git Repository.

The repository includes:

A Dockerfile for containerization
A src directory containing app.R, the main application script for a sample shiny app.
A rshiny-server-template.yaml file is available under the openshift directory, providing a ready-to-use OpenShift Template for deploying Shiny applications.

Always remember the Dockerfile needs to specify the base image i.e. dukegcb/openshift-shiny-verse:4.1.2, additional package requirements, and the location of your Shiny application code under src directory.

You can update the contents of your forked repository with your own Dockerfile and src directory containing your Shiny app files.

For example, if your app is located in the src directory and requires the here package (you can comment it out if no additional packages are needed), your Dockerfile should look like this:

FROM dukegcb/openshift-shiny-verse:4.1.2
RUN install2.r here
ADD ./src /srv/code

Important Note

The install2.r script is a simple utility to install R packages that is provided by the rocker images.

Deploy your shiny app using the OpenShift Web console

Here, we walk through the process of creating a simple R Shiny Web Server using an OpenShift Template, which bundles all the necessary resources required to run it, such as ImageStream, BuildConfig, Deployment, Route, Service, etc., and then initiates and deploys a Shiny application from that template.

An OpenShift template file, rshiny-server-template.yaml, is available within the Git Repository under the openshift directory.

More about Writing Templates

For more options and customization please read this.

Click the "Import YAML" button, represented by the "+" icon in the top navigation bar, or navigate to the From Local Machine section and select Import YAML, as shown below:

Next, the Import YAML editor box will open, as shown below:
Either drag and drop the locally downloaded rshiny-server-template.yaml file or copy and paste its contents into the opened Import YAML editor box, as shown below:
You need to find the Developer Catalog section and then select All services option as shown below:
Then, you will be able to use the created Developer Catalog template by searching for "rshiny" on catalog as shown below:
Once selected by clicking the template, you will see Instantiate Template web interface as shown below:
Based on our template definition, we request that users input some variables to initate the R Shiny Server.
Variables

All variables are mandatory for the application to be created.
- APP_NAME - Name used for the app
- APP_LABEL - Label used for the app
- APP_GIT_URI - GitHub repository URL
- APP_GIT_BRANCH - Git branch to build from
- REPO_DOCKERFILE_PATH - Location of the shiny app Dockerfile
- IMAGE_TAG - Tag for the built image
- NAMESPACE - Namespace where the application will be deployed
- PROBE_INITIAL_DELAY - Initial delay in seconds for liveness and readiness probes
- PROBE_TIMEOUT - Timeout in seconds for liveness and readiness probes
Important: Update the Variable Values According to Your Own Configuration!

It is essential to update the variable values in the OpenShift template to align with your specific configuration. Ensure that these values are adjusted according to your environment and requirements before deployment. If variable values are not explicitly provided, the template will automatically use its default values.
Once successfully initiated, you can either open the application URL using the Open URL icon as shown below or you can naviate to the route URL by navigating to the "Routes" section under the Location path as shown below:
Finally, you will be able to see the R Shiny app!

Modifying uploaded templates

You can edit a template that has already been uploaded to your project: oc edit template <template>.

Deploy your shiny app using the OpenShift CLI (`oc`)

Prerequisites:

Setup the OpenShift CLI (oc) Tools locally and configure the OpenShift CLI to enable oc commands. Refer to this user guide.

Information

Some users may have access to multiple projects. Run the following command to switch to a specific project space: oc project <your-project-namespace>.

Please confirm the correct project is being selected by running oc project, as shown below:
```
oc project
Using project "<your_openshift_project_to_add_r_shiny_app>" on server "https://api.shift.nerc.mghpcc.org:6443".
```

Deploy your R Shiny application

Process and apply template using default values from the template and passing your application specific parameters.

oc process -f ./openshift/rshiny-server-template.yaml \
   -p APP_GIT_URI=<YOUR_GIT_REPO> \
   -p APP_GIT_BRANCH=<YOUR_GIT_BRANCH> \
   -p REPO_DOCKERFILE_PATH=<PATH_TO_DOCKERFILE_IN_YOUR_REPO> \
   -p NAMESPACE=$(oc project --short) \
   | oc create -f -

For example, the command will look like this:

oc process -f ./openshift/rshiny-server-template.yaml \
    -p APP_GIT_URI=https://github.com/nerc-project/rshiny-testapp \
    -p APP_GIT_BRANCH=main \
    -p REPO_DOCKERFILE_PATH="Dockerfile" \
    -p NAMESPACE=$(oc project --short) \
    | oc create -f -

Important: Default Template Values Will Be Used If Not Overridden!

If variable values are not explicitly provided, the template will automatically use its default values.

Deleting your application and all its resources

Either using the OpenShift Web console, you can Right click on the application box and then confirm to delete it as shown below:

Alternatively, you can use the OpenShift CLI i.e. oc commands to delete all application resources:

oc delete all -l app=<APP_LABEL>
oc delete svc <APP_NAME>-service
oc delete route <APP_NAME>-route
oc delete bc <APP_NAME>-build
oc delete deploy <APP_NAME>-deployment
oc delete imagestream <APP_NAME>-imagestream
oc delete template shiny-server-template