/ShinyStudio

a curated, out-of-the-box instance of ShinyProxy that includes RStudio, VS Code, NGINX, InfluxDB to offer a full-featured, easily reproducible, multi-user development environment.

Primary LanguagePowerShellMIT LicenseMIT

ShinyStudio

A Docker orchestration of open-source solutions to facilitate secure, collaborative development.

Overview

The ShinyStudio project is an orchestration of various open-source solutions with the goal of providing:

  • a secured, collaborative development environment for R, Python, PowerShell, and more.
  • a secured, convenient way to share apps and documents written in Shiny, RMarkdown, plain Markdown, or HTML.
  • easily reproducible, cross-platform setup leveraging Docker for all components.

There are two distributions of ShinyStudio, the image and the stack.

ShinyStudio Image

The ShinyStudio image, hosted on DockerHub, builds upon the Rocker project to include:

The image is great for a personal instance, a quick demo, or the building blocks for a very customized setup.

Jump to Setup the Image

ShinyStudio

ShinyStudio Stack

The ShinyStudio stack builds upon the image to incorporate:

  • NGINX for simple HTTPS support.
  • InfluxDB for tracking site usage.

The stack provides a more enterprise-ready distribution, as NGINX provides an simple solution for HTTPS, and site usage is stored in InfluxDB.

Moreover, each component of the stack is run in a Docker container for reproducibility, scalability, and security. Only the NGINX port is exposed on the host system; all communication between ShinyProxy and other components happens inside an isolated Docker network.

Jump to Setup the Stack

Setup

The setup has been verified to work on each of Docker (for Linux) and Docker Desktop (for Mac and Windows).

Note: when upgrading ShinyStudio, setup from scratch and migrate existing content/settings afterward.

The instructions below assume a functional instance of Docker.

Note: Setup must be run as a non-root user.

Image

To download and run the ShinyStudio image from DockerHub, first, create a docker network named shinystudio-net:

docker network create shinystudio-net

Then, execute docker run in the terminal for your OS:

  • Bash (Linux/Mac)
docker run -d --restart always --name shinyproxy \
    --network shinystudio-net \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e USERID=$USERID \
    -e USER=$USER \
    -e PASSWORD=password \
    -e CONTENTPATH="${HOME}/ShinyStudio" \
    -e SITEPORT=8080 \
    -p 8080:8080 \
    dm3ll3n/shinystudio
  • PowerShell (Windows)
docker run -d --restart always --name shinyproxy `
    --network shinystudio-net `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -e USERID=1000 `
    -e USER=$env:USERNAME `
    -e PASSWORD=password `
    -e CONTENTPATH="/host_mnt/c/Users/$env:USERNAME/ShinyStudio" `
    -e SITEPORT=8080 `
    -p 8080:8080 `
    dm3ll3n/shinystudio

Notice the unique form of the path for the CONTENTPATH variable in the Windows setup.

Once complete, open a web browser and navigate to http://<hostname>:8080. Log in with your username and the password password.

Stack

The stack distribution of ShinyStudio is delivered through the GitHub repo and introduces two additional requirements:

First, clone the repo and enter the new directory:

git clone https://github.com/dm3ll3n/ShinyStudio

cd ShinyStudio

Complete the setup using either the provided scripts or by executing the commands manually. Once complete, open a web browser and navigate to http://<hostname>:8080.

The default logins are:

username password
user user
admin admin
superadmin superadmin
  • readers: can only view content from “Apps & Reports”, “Documents”, and “Personal”.
  • admins: can view all site content and develop content with RStudio and VS Code.
  • superadmins: can view and develop site content across multiple instances of ShinyStudio.

Scripts

The quickest way to get up-and-running is to use the provided control scripts. The scripts are provided as both Bash scripts (.sh) and PowerShell scripts (.ps1); use the script that is appropriate for your OS.

The command below will create a new site configuration based on the template at configs/template, then start it.

# Bash
./control.sh start 8080

# OR

# PowerShell
./control.ps1 start 8080

Manual

To perform the setup without the provided scripts, first copy the configs/template directory and rename it according to the HTTP port that this new site will listen on.

# Bash
cp -R 'configs/template' 'configs/8080'

# OR

# PowerShell
Copy-Item 'configs/template' 'configs/8080' -Recurse

Then, set the required environment variables followed by docker-compose up:

  • Bash (Linux/Mac)
# specify the site's port (./configs/<port>)
export SITEPORT=8080

# specify where to store content.
export CONTENTPATH="./content"

# specify the HTTPS port defined in 'nginx.conf',
# or use a random high-port if SSL is not enabled.
export HTTPSPORT=$((50000 + RANDOM % 10000))

# use the current user ID and user name.
export USERID=$UID
export USER

# build and start the project; the project name is required.
docker-compose -p "shinystudio_${SITEPORT}" up -d --build
  • PowerShell (Windows)
# specify the site's port (./configs/<port>)
$env:SITEPORT = '8080'

# specify where to store content.
$env:CONTENTPATH = '/host_mnt/c/Users/$env:USERNAME/ShinyStudio/content'

# specify the HTTPS port defined in 'nginx.conf',
# or use a random high-port if SSL is not enabled.
$env:HTTPSPORT = (Get-Random -Minimum 50000 -Maximum 60000).ToString()

# use the current user ID and user name.
$env:USER = $env:USERNAME
$env:USERID = 1000

# build and start the project; the project name is required.
docker-compose -p "shinystudio_$($env:SITEPORT)" up -d --build

Develop

Open your IDE of choice and notice two important directories:

  • __ShinyStudio__
  • __Personal__

Files must be saved in either of these two directories in order to persist between sessions.

These two folders are shared between instances RStudio, VS Code, and Shiny Server. So, creating new content is as simple as saving a file to the appropriate directory.

Tools

The ShinyStudio image comes with…

  • R
  • Python 3
  • PowerShell

…and ODBC drivers for:

  • SQL Server
  • PostgresSQL
  • Cloudera Impala.

These are persistent because they are built into the image.

Persistent
__ShinyStudio__ directory Yes
__Personal__ directory Yes
Other directories No
R Libraries Yes
Python Packages Yes
PowerShell Modules Yes
RStudio User Settings Yes
VS Code User Settings Yes
Installed Apps No
Installed Drivers No

Configuration

The information below only applies to the ShinyStudio stack.

Many of the configuration options are accessible through the ShinyProxy configuration file, application.yml. Here, you can change the site title, change the authentication mechanism, and further refine access.

Review the ShinyProxy configuration documentation for all options.

Authentication

ShinyProxy supports various authentication mechanisms (basic, LDAP, social, …).

To change from basic auth (default) to LDAP auth, open the site’s configuration file (configs/8080/application.yml), locate the section below…

authentication: simple
users:
  - name: superadmin
    password: *change*me*
    groups: superadmins
  - name: admin
    password: *change*me*
    groups: admins
  - name: user
    password: *change*me*
    groups: readers

…and replace it with the following, after providing values appropriate for your environment:

ldap:
    url: ldap://mydomain.com/DC=mydomain,DC=com
    manager-dn: CN=svc.user,OU=Users,DC=mydomain,DC=com
    manager-password: ...
    user-search-base: 
    user-search-filter: (sAMAccountName={0})
    group-search-base: OU=Groups
    group-search-filter: (member={0})

Afterward, you may want to refine access to various apps using the access-groups option available to each:

access-groups: [ "reader-group", "admin-group", "superadmin-group" ]

SSL/TLS for HTTPS

To encrypt communication over HTTPS, edit the provided NGINX configuration file for the site in question (configs/8080/nginx.conf).

First, place the site’s certificate and key in configs/8080/certs/.

Then, uncomment the designated lines in nginx.conf and supply the desired HTTPS port in the three sections indicated in the file.

Finally, restart the site with:

./control.[sh/ps1] restart 8080

If configured properly, HTTP requests to ShinyProxy will be redirected to HTTPS.

References