Advanced Configuration for ShinyProxy

ShinyProxy is versatile. Learn about its configuration to make the most of this powerful piece of technology.

ShinyProxy is a software that can serve containerized web applications – including Shiny apps – without limits on the number of concurrent users. It comes with free enterprise features, such as authentication and authorization.

In the introductory ShinyProxy post I reviewed a very basic setup but did not go into details about the configuration. Let's review the most important configuration options for ShinyProxy.

The configuration is defined by the application.yml file in the /etc/shinyproxy folder. There are default values for the config options. The options you put in the YAML file will override the defaults. Here are the various sections of the YAML file.

General

The top part of the proxy block has some general properties that will affect the behaviour of ShinyProxy in general and will apply to all the apps you deploy.

proxy:
  title: ShinyProxy
#  logo-url: https://link/to/your/logo.png
  landing-page: /
  favicon-path: favicon.ico
  heartbeat-rate: 10000
  heartbeat-timeout: 60000
  port: 8080

...

title: the title is the text that is displayed in the top navigation bar of ShinyProxy beside the logo
logo-url: the URL of the logo beside the title in the top navigation bar of ShinyProxy (it can also be a file, file://...)
landing-page: the URL where the user is sent after logging in, the default / redirects the user to the list of applications
favicon-path: path to the favicon file to be used by ShinyProxy, the tiny PNG image that is displayed in the left corner of the browser tabs for easy recognition
heartbeat-rate: this is the time in milliseconds the user’s browser is sending a signal, called the heartbeat, to check in with the application, the default value is 10 seconds (10,000 ms)
heartbeat-timeout: this is the time in milliseconds the server waits after not receiving a heartbeat, when this time is passed the relevant proxy (instance of the app) will be released (the Docker container stopped) – 60 seconds (60,000 ms)
port: port to be used by ShinyProxy, the default port is 8080

Backend

ShinyProxy supports different backends, Docker (default), Docker Swarm, and Kubernetes.

proxy:

...

  docker:
    cert-path: /home/none
    url: http://localhost:2375
    port-range-start: 20000

...

cert-path: path to the folder that contains the certificate files (ca.pem, cert.pem and key.pem) when using secure connections (i.e. HTTPS), this way it is not just the traffic from the browser to ShinyProxy gets encrypted, but also the traffic between ShinyProxy and the Docker daemon, the default is set to /home/none (no certificates)
url: URL and port on which to connect to the Docker daemon; the default value of http://localhost:2375 does not connect over a secure connection and needs to be changed to https://localhost:2375 when HTTPS and certificates are set up in production
port-range-start: every Docker container will be assigned a port on the Docker host to which the ShinyProxy will proxy the traffic of a particular user, this property defines the port assigned to the 1st container that is started

Authentication

ShinyProxy supports many different types of authentication, starting from none (no authentication) and simple (user names and passwords defined in the config file) to various types of authentication servers and 3rd party providers. I review simple authentication here.

proxy:

...

  authentication: simple
  admin-groups: admins
  # Example: 'simple' authentication configuration
  users:
  - name: admin
    password: password
    groups: admins
  - name: user
    password: password
    groups: users

...

authentication: authentication method (one of ldap, kerberos, keycloak, openid, saml, social, simple or none); see the relevant section below for configuration details regarding each of these authentication methods;
admin-groups: one (e.g. admin) or more groups (e.g. [admins1, admins2]) that have access to the administrative interface of ShinyProxy to view active sessions, defined according to the authentication backend)
users: list here the users, each one has 3 different properties, name and password to log in with, and groups that is used to define access to the apps via the access-groups property – the access-groups field allows authorizing access per application

Two environmental variables are provided to the Shiny applications by ShinyProxy after successful authentication by a user, the user name (SHINYPROXY_USERNAME) and groups that the user is a member of (SHINYPROXY_USERGROUPS, comma-separated value). Use these values to personalize the application.

Applications

All Shiny apps served by ShinyProxy have their configuration listed in the specs block in the configuration file.

proxy:

...


  specs:
  - id: 01_hello
    display-name: Hello Shiny App
    description: A simple reactive histogram
    container-cmd: ["R", "-e", "shiny::runApp('/home/app')"]
    container-image: registry.gitlab.com/analythium/shinyproxy-hello/hello:latest
    logo-url: https://github.com/analythium/shinyproxy-1-click/raw/master/digitalocean/images/app-hist.png
    access-groups: [admins, users]
  - id: 02_hello
    display-name: Demo Shiny App
    description: App with sliders and file upload
    container-cmd: ["R", "-e", "shiny::runApp('/home/app')"]
    container-image: analythium/shinyproxy-demo:latest
    logo-url: https://github.com/analythium/shinyproxy-1-click/raw/master/digitalocean/images/app-dots.png
    access-groups: [admins]

...

id: the identifier of the application, this is also the URL path the app is going to be available through the ShinyProxy API endpoints either as /app/<id> (standard ShinyProxy interface with a toolbar, servers the Shiny app in an iframe) or /app_direct/<id> (without the iframe and navigation bar)
display-name: the name that will be displayed for the app on the ShinyProxy landing page as well as in the browser tab once the application is opened
container-cmd: the command that is run when the user launches the Docker container, the CMD line from the end of the Dockerfile
container-image: the Docker image tag to be started for every new user of this app
logo-url: the URL or a local file (file://...) of an image used as the logo for an application, when none of the applications in the application.yml specifies a logo-url field, the landing page will be a bullet list
access-groups: one or more groups ([group1, group2]) that the user needs to belong to in order to gain access to the app, apps for which access-groups are not specified will be handled as “public” applications in the sense that all authenticated users will be able to access these applications.

Logging

Information about the application events will be logged into the standard output stream of the ShinyProxy process. You can specify a file where logs should be written, or set up more detailed statistics to be collected.

...

logging:
  file:
    name: shinyproxy.log

You can also configure ShinyProxy to write the standard error and standard output streams of the R process running the Shiny app in the container. This container level logging is specified under the proxy block via container-log-path property.

Conclusions

I only covered the most important configuration options for ShinyProxy and this post already got fairly long. This will be enough to get you started with adding your apps to the config file. But there is a lot more options to explore depending on your use case.

If you need a quick way of spinning up a virtual machine with ShinyProxy already installed, try the ShinyProxy 1-click app from the Digitalocean Marketplace for $5 a month. I explain the setup in this short video:

Don't forget to shut down the server if you don't need it anymore.