By: Peter Solymos
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 is8080
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
andkey.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 ofhttp://localhost:2375
does not connect over a secure connection and needs to be changed tohttps://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 ofldap
,kerberos
,keycloak
,openid
,saml
,social
,simple
ornone
); 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
andpassword
to log in with, andgroups
that is used to define access to the apps via theaccess-groups
property – theaccess-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, theCMD
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 theapplication.yml
specifies alogo-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 DigitaloceanMarketplace for $5 a month. I explain the setup in this short video:
Top comments (0)