Version 3.0.2 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Getting Started

Prerequisites

Java

ShinyProxy is written using mature and robust Java technology and you will need a Java 8 runtime environment to run ShinyProxy. We recommend the use of OpenJDK or a multi-platform distribution of OpenJDK like Zulu. Of course, Oracle Java will do too.

To check your version of Java is Java 8 (or higher), run

java -version

which should display something along

openjdk version "1.8.0_72"
OpenJDK Runtime Environment (Zulu 8.13.0.5-linux64) (build 1.8.0_72-b15)
OpenJDK 64-Bit Server VM (Zulu 8.13.0.5-linux64) (build 25.72-b15, mixed mode)

Docker

Installation

Every user of ShinyProxy will use its private Docker container when running a Shiny application. When running ShinyProxy you will therefore need to set up docker on your host. Docker has very complete installation instructions:

and also provide information on how to get docker up and running in the cloud.

To check whether the docker daemon is up and running, use

sudo systemctl status docker

on GNU/Linux or the equivalent on your platform. This will display something along

● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-07-11 09:52:10 UTC; 3min 45s ago
...

Docker startup options

ShinyProxy needs to connect to the docker daemon to spin up the containers for the Shiny apps. ShinyProxy can connect to the daemon on port 2375 of the docker host. In order to allow for connections on port 2375, the startup options need to be edited.

  • on an Ubuntu 14.04 LTS system (or a similar system that uses upstart) this can be set in the /etc/default/docker file as follows:

    [...]
    
    # Use DOCKER_OPTS to modify the daemon startup options.
    DOCKER_OPTS="-H tcp://127.0.0.1:2375 -H unix://"
    

    To restart docker use

    sudo service docker restart
    
  • on an Ubuntu 16.04 LTS, 18.04 LTS and 20.04 LTS or a CentOS 7, RHEL 7, CentOS 8 and RHEL 8 system (or a similar system that uses systemd) with Docker installed from the Docker repositories, one can change the configuration using:

    sudo systemctl edit docker
    

    This command opens your default editor, add the following content to the file:

    [Service]
    ExecStart=
    ExecStart=/usr/bin/dockerd -H unix:// -D -H tcp://127.0.0.1:2375
    

    Next, save the file, close the editor and restart Docker using:

    sudo systemctl restart docker
    

    Note: it is also possible to edit /lib/systemd/system/docker.service and replace the relevant line with

    /usr/bin/dockerd -H unix:// -D -H tcp://127.0.0.1:2375
    

    but these settings will be lost upon updating Docker on your system and are therefore not recommended. More background on the use of the override.conf file can be found in this Docker article.

  • on a CentOS 7 (or RHEL 7) system, where docker is installed from the official CentOS repositories, edit the /etc/sysconfig/docker file, so that the OPTIONS variable looks like:

    # /etc/sysconfig/docker
    
    # Modify these options if you want to change the way the docker daemon runs
    OPTIONS='--selinux-enabled --log-driver=journald --signature-verification=false -H tcp://127.0.0.1:2375 -H unix://'
    if [ -z "${DOCKER_CERT_PATH}" ]; then
        DOCKER_CERT_PATH=/etc/docker
     fi
    
  • on a Windows system, edit the file C:\ProgramData\Docker\config\daemon.json and add:

    "hosts": ["tcp://127.0.0.1:2375"]
    

    To restart Docker use

    service docker restart
    

    More information on configuring Docker on Windows can be found here. Also see this guide for running GNU/Linux containers.

Download

ShinyProxy can be downloaded from our Download page or directly from Github.

Running ShinyProxy

Pulling the demo image

In order to run ShinyProxy, you need… Shiny apps. In ShinyProxy such Shiny apps are typically shipped in docker containers and the openanalytics/shinyproxy-demo is a demo image that has been made available to start playing with Shiny Proxy.

Once docker is installed on your system, you can pull (i.e. download) the docker image with the demo applications using

sudo docker pull openanalytics/shinyproxy-demo

or the equivalent commands on your system. You can check whether you already have openanalytics/shinyproxy-demo on your system using

sudo docker images | grep shinyproxy

which should display something along

openanalytics/shinyproxy-demo        latest              fce70ee5ba84        15 hours ago        787 MB

Note: since ShinyProxy 3.0.0, ShinyProxy automatically pulls the image when it is not yet available on the Docker host.

Running ShinyProxy

ShinyProxy can be run using the following command

java -jar shinyproxy-3.0.2.jar

less than 10 seconds later, you can point your browser to http://localhost:8080 and use your Shiny apps! When not providing a custom configuration file, ShinyProxy uses a fallback configuration and allows to login using the following credentials:

  • username: jack and password: password
  • username: jeff and password: password

More advanced information on the usage and configuration of ShinyProxy is available on the Configuration page.

See the deployment page page on how to create a production ready deployment for ShinyProxy.