Getting Started

Prerequisites

Java

ShinyProxy is written using mature and robust Java technology, therefore you will need a Java 17 runtime environment to run ShinyProxy. We recommend the use of OpenJDK, using the packages of your Linux distribution, Eclipse Temurin (Adoptium), Zulu or Amazon Corretto.

To check whether your version of Java is at least version 17, run:

java -version

which should display something along:

openjdk 17.0.10 2024-01-16
OpenJDK Runtime Environment (build 17.0.10+7)
OpenJDK 64-Bit Server VM (build 17.0.10+7, 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:

installing Docker on Linux
installing Docker on Mac OS
installing Docker on Windows

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
...

If Docker is not running start it using:

sudo systemctl start docker
sudo systemctl enable docker

Access to Docker daemon

ShinyProxy needs to connect to the docker daemon to spin up the containers for the Shiny apps. The most secure way is to use a Unix socket. This requires that ShinyProxy has permission to the Unix socket (which is a special file). If your current user already has access to Docker socket, you can skip the following steps.

Warning

Previous versions of this documentation instructed to make Docker listen on a regular TCP port (2375). This is less secure than using the socket, since every user and process on the system has access to this TCP port and thus access to the Docker Daemon. Please change your configuration to use a Unix socket. See the relevant Docker docs for more information.

Create a new user for ShinyProxy:

sudo useradd --system \
  -m \
  --home-dir /home/shinyproxy \
  --shell /bin/bash \
  -G docker \
  shinyproxy

This command creates a shinyproxy user and add this user to the docker group, giving the user access to the Docker daemon.

Next open a shell using this user (make sure to run all following commands using this shell):

sudo -i -u shinyproxy

Download

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

Using wget you can download the file directly on a server:

wget https://shinyproxy.io/downloads/shinyproxy-3.1.0.jar

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

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

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 (as explained above make sure to run this in the shell that is using the shinyproxy user):

java -jar shinyproxy-3.1.0.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. Make sure to name the configuration file application.yml and create it in the same directory as the jar file.

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

Tips:

run the java command using the shinyproxy user (e.g. by starting a new shell)
run the java command in the same directory as the jar file
create the config file in the same directory as the jar file
make sure the jar file is owned by the shinyproxy user (otherwise you might get unable to access jar file), you can restore this by running:
```
chown shinyproxy:shinyproxy shinyproxy-3.1.0.jar
```
In addition, the shinyproxy user should have access to the directory containing the jar file.