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.
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,
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
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 (
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
url: URL and port on which to connect to the Docker daemon; the default value of
http://localhost:2375does not connect over a secure connection and needs to be changed to
https://localhost:2375when 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
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
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,
passwordto log in with, and
groupsthat is used to define access to the apps via the
access-groupsproperty – the
access-groupsfield 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.
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
CMDline 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
logo-urlfield, 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-groupsare not specified will be handled as “public” applications in the sense that all authenticated users will be able to access these applications.
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
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.