Upgrading

ShinyProxy is designed to be easy to update. This page describes the full process in detail.

Release notes

Read the release notes on the Downloads page. For every release, they contain a list of breaking (configuration) changes or specific upgrade instructions. Although, in general we try to limit the number of configuration changes, some releases require a small update to the application.yml file.

In the past it was sometimes necessary to use a new (empty) Redis database (because the data format of Spring sessions has changed). Starting with version 3.2.0, this is no longer necessary and the existing Redis database (with both user and app sessions) can be re-used.

Update the HTML templates

This is only necessary if you have modified the HTML templates, by placing custom HTML files along the application.yml file. Almost every update of ShinyProxy modifies the HTML templates. The best way to update the templates, is by downloading the updated files from GitHub and re-applying your changes on top of the new files. We don’t advice to do it the other way, i.e. updating your existing templates to match the changes made in ShinyProxy. A merge-tool like meld can help with making the necessary changes (but again, it’s best to re-apply your changes on top of the new templates from GitHub).

You might want to test the updated templates before deploying them in production.

Check the Java version

With every update of ShinyProxy we update the dependencies to benefit from the latest features and security fixes. Some releases require a newer Java version. If this is the case, the releases notes contain which Java version is required. You only need to install a newer java version when ShinyProxy is installed using the jar file or the Linux packages. The Docker image of ShinyProxy automatically uses the correct version of Java, hence requiring no manual changes.

The exacts steps for installing a new version of Java depends on your operation system. As an example, this are the steps for Ubuntu:

sudo apt update
sudo apt install apt install openjdk-21-jre
sudo update-java-alternatives --set /usr/lib/jvm/java-1.21.0-openjdk-amd64

Next, verify that the correct version is being used:

java --version

Update and restart ShinyProxy

Without the ShinyProxy Operator

Warning

ShinyProxy will be unavailable when restarting ShinyProxy. In addition, when not using app persistence or app recovery sessions and running apps are lost after the restart. Therefore, it’s better to first stop all apps through the admin panel or stop and remove all containers.

We strongly recommend to use the ShinyProxy Operator to benefit from zero-downtime updates and configuration changes.

jar file: simply replace the file and re-run it
Linux package: download the new package and install it in the same way as a new install. Next, restart ShinyProxy using:
```
sudo systemctl restart shinyproxy
```
ShinyProxy in docker: note down the command used for the currently running container. Next, change this command (and execute it) to use a new version of ShinyProxy by changing the tag of the image. If you are using a custom Docker image, you first have to build a image using the new version of ShinyProxy.
To update the example on GitHub, follows these steps:
1. update the ShinyProxy tag in the Dockerfile
2. build the image sudo docker build . -t shinyproxy-example
3. find the id of the existing container using sudo docker ps
4. stop the existing container: sudo docker stop <id>
5. run the new container using the sudo docker run ... command provided on GitHub.

With the ShinyProxy Operator

The ShinyProxy Operator allows to update ShinyProxy (and its configuration) without any downtime and without losing any existing sessions or running apps. Note that starting with version 2.2 of the operator this is also supported on pure Docker machines (i.e. without using Kubernetes).

Updating ShinyProxy with the operator is as simple as updating the image property in the configuration. For example:

Old config:

proxy:
  title: Open Analytics Shiny Proxy
  specs:
    # ...

image: openanalytics/shinyproxy:3.1.1

New config:

proxy:
  title: Open Analytics Shiny Proxy
  specs:
  # ...

image: openanalytics/shinyproxy:3.2.0

The tutorial for Kubernetes and Docker explain how to apply this configuration change.

Check the ShinyProxy logs

After updating ShinyProxy it’s a good idea to have a look at the logs generated by ShinyProxy. ShinyProxy logs warnings if you are using a removed feature or configuration property.