Configuration

Overview

The server configuration is mainly done in a file named application.yml. If the default values must be overridden, this can be done by adding a file application.yml in the same folder where you launch the shinyproxy-*.jar file and specify properties in the YAML format. The standard configuration has the following values:

shiny:
  proxy:
    title: Open Analytics Shiny Proxy
    logo-url: http://www.openanalytics.eu/sites/www.openanalytics.eu/themes/oa/logo.png
    landing-page: /
    heartbeat-rate: 10000
    heartbeat-timeout: 60000
    port: 8080
    authentication: ldap
    admin-groups: scientists
    # Simple auth configuration
    users:
    - name: jack
      password: password
      groups: scientists
    - name: jeff
      password: password
      groups: mathematicians
    # LDAP configuration
    ldap:
      url: ldap://ldap.forumsys.com:389/dc=example,dc=com
      user-dn-pattern: uid={0}
      group-search-base:
      group-search-filter: (uniqueMember={0})
      manager-dn: cn=read-only-admin,dc=example,dc=com
      manager-password: password
    # Docker configuration
    docker:
      cert-path: /home/none
      url: http://localhost:2375
      port-range-start: 20000
  apps:
  - name: 01_hello
    display-name: Hello Application
    description: Application which demonstrates the basics of a Shiny app
    docker-cmd: ["R", "-e shinyproxy::run_01_hello()"]
    docker-image: openanalytics/shinyproxy-demo
    groups: scientists, mathematicians
  - name: 06_tabsets
    docker-cmd: ["R", "-e shinyproxy::run_06_tabsets()"]
    docker-image: openanalytics/shinyproxy-demo
    groups: scientists

logging:
  file:
    shinyproxy.log

General

The first block of configuration in the application.yml file concerns general configuration values for the ShinyProxy application:

  • title: title that is displayed in the ShinyProxy navigation bar;
  • logo-url: url of the logo that is displayed in the ShinyProxy navigation bar;
  • landing page: landing page resource; default value is /;
  • heartbeat-rate: the user's browser will sent a heartbeat call every heartbeat-rate milliseconds; default value is 10000 (10 seconds);
  • heartbeat-timeout: if the server does not receive a heartbeat for heartbeat-timeout milliseconds, the relevant proxy will be released (and the container stopped); default value is 60000 (60 seconds);
  • port: port to be used by ShinyProxy; the default port is 8080.
  • authentication: authentication method; one of ldap (default), simple or none
  • admin-groups: one or more groups (as defined in the authentication back-end) that have access to the administrative interface of ShinyProxy e.g. to view and manage active sessions; multiple groups are separated by commas.

Besides the basic configuration options described above, there are also some more advanced configuration options that are not part of the default configuration:

  • container-wait-time: timeout for the container to be available to ShinyProxy; defaults to 20s (20000):
shiny:
  proxy:
    [...]
    container-wait-time: 20000

Note that a container is considered to be 'available' if its HTTP listener responds with status 200.

  • hide-navbar: boolean; if set to true the navigation bar at the top will be hidden; this may be useful when ShinyProxy is deployed as part of larger applications

Authentication

LDAP

With the default values (authentication: ldap), authentication will be done against the LDAP server at ldap.forumsys.com; to log in one can use the user name "tesla" and password "password".

In order to use it with your LDAP directory, edit the following fields

  • url: the LDAP connection string, composed of the URL and base DN of the LDAP directory
  • user-dn-pattern: pattern of the distinguished name for a user;
  • group-search-base: search base for LDAP groups (for authorization purposes);
  • group-search-filter: filter used to search for group membership;
  • manager-dn: the distinguished name of the user used to bind to the LDAP directory; leave empty if the initial bind is anonymous;
  • manager-password: the password of the user used to bind to the LDAP directory; can be omitted if manager-dn is empty (i.e. when the initial bind is anonymous).

When using a FreeIPA server for managing identities (e.g. the standard on RHEL), the configuration with the default directory tree will be:

ldap:
      url: ldaps://example.com:636/dc=example,dc=com
      manager-dn: uid=shinyproxy,cn=sysaccounts,cn=etc,dc=example,dc=com
      manager-password: xxxxxxxxxxxx
      group-search-base: cn=groups,cn=accounts
      group-search-filter: (member={0})
      user-dn-pattern: uid={0},cn=users,cn=accounts

Note:

  • in this example uid=shinyproxy,cn=sysaccounts,cn=etc,dc=example,dc=com is a specific system account created to bind against the FreeIPA LDAP directory on behalf of ShinyProxy;
  • the user name of the authenticated user is made available to the Shiny application via the environment variable SHINYPROXY_USERNAME
  • if the ldaps protocol is used (as above), make sure to also disable basic security using
# must be disabled for ldaps
security:
  basic:
    enabled: false    

at the bottom of the application.yml configuration file.

Single-Sign On / Keycloak

A second type of authentication is Keycloak authentication, a very powerful option that delegates authentication and authorization to the open source identity and access management system Keycloak supported by Red Hat. Many advanced features are available to ShinyProxy such as User Federation, Identity Brokering and Social Login.

Keycloak authentication can be configured using

shiny:
  proxy:

    [...]

    authentication: keycloak

in the application.yml file. The details related to the application identifiers and secrets for each of the social platforms can be configured in a separate keycloak block:

shiny:
  proxy:

  [...]

    keycloak:
      realm: yoursso
      auth-server-url: http://yoururl.com:8180/auth
      resource: yourresource
      credentials-secret: your-credentials-secret

Further documentation on setting up Keycloak can be found here.

Social Authentication

A third type of authentication offered by ShinyProxy besides LDAP and Keycloak is so-called social authentication. This type of authentication allows users to log in with

  • Facebook,
  • Twitter,
  • Google,
  • Github or
  • Linkedin

accounts into ShinyProxy.

Social authentication can be configured using

shiny:
  proxy:

    [...]

    authentication: social

in the application.yml file. The details related to the application identifiers and secrets for each of the social platforms can be configured in a separate social block:

shiny:
  proxy:

  [...]

    social:
      facebook:
        app-id: yourfacebookappid
        app-secret: yourfacebookappsecret
      twitter:
        app-id: yourtwitterappid
        app-secret: yourtwitterappsecret
      google:
        app-id: yourgoogleappid
        app-secret: yourgoogleappsecret
      github:
        app-id: yourgithubappid
        app-secret: yourgithubappsecret
      linkedin:
        app-id: yourlinkedinappid
        app-secret: yourlinkedinappsecret

Since no authorization is offered by the social platforms, authorization logic is not implemented and authenticated users will be able to access all public applications.

Simple Authentication

Besides LDAP and social authentication, ShinyProxy also offers the possibility to define users and groups inside the application.yml file. In order to select this authentication method, one needs to choose the simple authentication method:

shiny:
  proxy:

    [...]

    authentication: simple

The example configuration demonstrates how users and groups can be specified:

shiny:
  proxy:
    users:
    - name: jack
      password: password
      groups: scientists
    - name: jeff
      password: password
      groups: mathematicians

Since passwords are contained in clear text in the application.yml file, this is not a secure way to set up authentication, but can be useful for demonstration purposes (e.g. in the absence of a network connection) or for very specific use cases.

Note:

  • the user name of the authenticated user is made available to the Shiny application via the environment variable SHINYPROXY_USERNAME

No authentication

In some scenarios, one wants to disable the ShinyProxy authentication. This can be done using

shiny:
  proxy:

    [...]

    authentication: none

Note:

  • with authentication: none the environment variable SHINYPROXY_USERNAME inside the Docker container will contain a random hash instead of the user name; if a user name needs to be passed from an external application it may be more useful to pass this information to the Shiny application via the URL (see this article).

Docker

  • cert-path: path to the folder that contains the certificate files (ca.pem, cert.pem and key.pem) used for encrypted traffic to the docker daemon; if the files have other names or are located in different folders, symbolic links can be used (for ca.pem, cert.pem and key.pem) that point to the actual certificate files. If a non-existing path is used as cert-path, traffic will not be encrypted; the default value for cert-path is set to /home/none;
  • url: URL and port on which to connect to the docker daemon; the default value of http://localhost:2375 does not connect over TLS; this is not recommended for production environments;
  • 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; the value of port-range-start will be the port assigned to the first container that is started; by default the first port will be 20000 (second 20001, third 20002 etc.).

Apps

Every single Shiny app served by Shiny Proxy has its own configuration block under apps:

    apps:
  - name: 01_hello
    docker-cmd: ["R", "-e shinyproxy::run_01_hello()"]
    docker-image: openanalytics/shinyproxy-demo
    groups: [scientists, mathematicians]
  - name: 06_tabsets
    docker-cmd: ["R", "-e shinyproxy::run_06_tabsets()"]
    docker-image: openanalytics/shinyproxy-demo
    groups: [scientists]

For each app, four fields can be specified:

  • name: the name that will be displayed for the app on the ShinyProxy landing page;
  • docker-cmd: the command that will be run when the Docker container is launched; typically this command will be the R command ("R") as well as the command that will launch the Shiny app ("-e shinyproxy::run_01_hello()");
  • docker-image: name of the docker image to be started for every new user of this app; by default a demo image (openanalytics/shinyproxy-demo) will be used;
  • groups: one or more groups (e.g. LDAP groups) a user needs to belong to in order to gain access to the app; this field allows to authorize access per app; to test the authorization with LDAP authentication, one can use gauss with password password as an example mathematician; user tesla with password password is one of the example scientists. Other users are described here.

Note:

  • apps for which groups are not specified will be handled as "public" applications in the sense that all authenticated users will be able to access these applications.

Besides the basic configuration options described above, there are also some more advanced configuration options that are not part of the default configuration:

  • docker-dns: a comma-separated list of IP addresses that are added as server lines in the /etc/resolv.conf file of the container; this is the equivalent of launching the container with a --dns option.
  • docker-env-file: a path to a file in which environment variables are specified to be passed to the container; this can be configured using
    docker-env-file: /path/to/env-file

and is equivalent to docker run --env-file.

  • docker-memory: memory limit for the Shiny application (e.g. 256m or 4g); units can be one of b, k, m, or g and the minimum is 4m. This is the equivalent of launching the container with a --memory option.
  • docker-network: facilities to set the networking of the container. This is the equivalent of launching the container with a --network option (and defaults to bridge which is also the Docker default).
  • docker-volumes: list of docker volumes to mount into the container; can be specified along
 docker-volumes: [ "/host/path1:/container/path1", "/host/path2:/container/path2" ]

and implements the functionality of docker run --volume.

  • logo-url: the URL to an image that can be used as the logo for an application; if none of the applications in the application.yml specifies a logo-url field, the landing page will present the applications as a bullet list (cf. the default presentation in the openanalytics/shinyproxy-demo image).

Logging

In the default configuration, simple logging is enabled

logging:
  file:
    shinyproxy.log

and with this setting ShinyProxy will not only log to the console but also to the shinyproxy.log file in the directory in which it was started. The logging field offers much more and gives access to fine-grained and powerful logging configuration as detailed here. If you want e.g. to debug LDAP authentication, you can use something along

logging:
  level:
    org.springframework.security.ldap.authentication: DEBUG
    org.springframework.security.ldap.userdetails: DEBUG
  file:
    shinyproxy.log

instead.

Usage Statistics

ShinyProxy supports the tracking and saving usage statistics to see which apps are popular and by whom these are used. Currently, an influxDB back-end can be used for this purpose. With this back-end events are posted (via HTTP) to an InfluxDB instance.

Two properties allow to configure the posting of the events:

  • usage-stats-url: the URL of the InfluxDB instance and its query port; a typical value is http://localhost:8086
  • usage-stats-db: the name of the database in which to store the ShinyProxy specific events; a typical value is shinyproxy_usagestats

In the default configuration these properties are not set and, as a consequence, tracking of usage statistics in an InfluxDB instance is not enabled.