Shiny Server enables users to host and manage Shiny applications on the Internet. Shiny is an R package which uses a reactive programming model to simplify the development of R-powered web applications. Shiny Server can manage R processes running various Shiny applications over different URLs and ports. Using Shiny Server offers a variety of benefits over simply running Shiny in R directly. These features allow the administrator to:
Shiny Server is currently only supported on the Linux operating system. We officially support the following distributions:
We currently only support the x86-64 architecture. As described in the Installation section, you will install R and the Shiny package prior to installing Shiny Server. Root privileges will be required both in the installation process and also at runtime.
The Shiny Server installer does not come with R, nor does it provide the Shiny R package. Below are the steps for installing each of them separately.
If you had previously installed Shiny Server 0.3.x or 0.4.x, please see the relevant section before proceeding to ensure a seamless upgrade:
Installing R
Shiny Server recommends an installation of R version 3.0 or higher. To install the latest version of R you should first add the CRAN repository to your system as described here:
You can then install R using the following command:
$ sudo apt-get install r-baseNOTE: if you do not add the CRAN Debian or Ubuntu repository as described above this command will install the version of R corresponding to your current system version. Since this version of R may be a year or two old it is strongly recommended that you add the CRAN repositories so you can run the most up to date version of R.
At this point, follow the instructions in Install Shiny to setup the necessary packages in R.
Once Shiny is installed, you can begin the installation of Shiny Server. You should have been provided with a .deb installer for Shiny Server. If you only have a link to this file, you can use wget to download the file to the current directory. You will need to first install the gdebi-core package to install Shiny Server and its dependencies. Once the .deb file is available locally, run the following commands to complete the installation of Shiny Server.
sudo apt-get install gdebi-core
sudo gdebi shiny-server-1.4.0.debThis will install Shiny Server into /opt/shiny-server/, with the main executable in /opt/shiny-server/bin/shiny-server and also create a new shiny user. The rest of this guide will document the intricacies of how you can configure and manage Shiny Server. If you're just looking to get up and running quickly, we recommend you look at the Quick Start section in the appendix which will walk you through the process of installing and configuring a Shiny application.
Prerequisites
Shiny Server recommends an installation of R version 3.0 or higher. Shiny Server has several dependencies on packages (including R itself) found in the Extra Packages for Enterprise Linux (EPEL) repository. If you don't already have this repository available you should add it to your system using the instructions found here: https://fedoraproject.org/wiki/EPEL. On some distributions of RedHat/CentOS, the R package references dependencies that are not available by default. In this case, you may need to edit the /etc/yum.repos.d/redhat.repo file to enable the rhel-6-server-optional-rpms (by setting enabled = 1) before you can install the R package.
After enabling EPEL you should then ensure that you have installed the version of R available from EPEL. You can do this using the following command:
$ sudo yum install R At this point, follow the instructions in Install Shiny to setup the necessary packages in R.
Once Shiny has been installed, you can begin the installation of Shiny Server. You should have been provided with an RPM file which contains Shiny Server and all of its dependencies (other than R and Shiny). You can install this rpm file using yum. If you have only a link to the RPM file, you can use wget to download the file to the current directory. You can install this RPM file using yum.
$ sudo yum install --nogpgcheck shiny-server-1.4.0.rpmThis will install Shiny Server into /opt/shiny-server/, with the main executable in /opt/shiny-server/bin/shiny-server and also create a new shiny user. The rest of this guide will document the intricacies of how you can configure and manage Shiny Server. If you're just looking to get up and running quickly, we recommend you look at the Quick Start section in the appendix which will walk you through the process of installing and configuring a Shiny application.
Prerequisites
Shiny Server recommends an installation of R version 3.0 or higher. You can install R for SUSE Linux Enterprise Server using the instructions on the CRAN SUSE download page: http://cran.rstudio.com/bin/linux/suse/. Note that the binaries suggested here have one additional requirement that isn’t satisfied using the default repositories. Before installing R you should install the libgfortran43 package. This package is available from the SUSE Linux Enterprise SDK. If the SDK repository is available in your environment you can install libgfortran43 as follows:
$ sudo zypper install libgfortran43At this point, follow the instructions in Install Shiny to setup the necessary packages in R.
Once R and Shiny have been installed, you can begin the installation of Shiny Server.
Additional Prerequisites for SLES
The Shiny Server Professional RPM binaries link to version 0.9.8 of the openssl and libcrypo shared libraries. On RedHat systems the shared library files have a suffix of ".6" (e.g. libcrypo.so.6) whereas on SLES they have a suffix of "0.9.8". As a result you should soft-link the existing 0.9.8 shared libraries to a version with a .6 suffix by running the following commands:
$ sudo ln -f -s /usr/lib64/libssl.so.0.9.8 /usr/lib64/libssl.so.6
$ sudo ln -f -s /usr/lib64/libcrypto.so.0.9.8 /usr/lib64/libcrypto.so.6The Shiny Server Professional metrics and monitoring features use a set of Python scripts to introspect the system for performance information. As part of installation a Python native extension needs to be built, and this requires the python-devel-26 package available from the SUSE Linux Enterprise SDK. If the SDK repository is available in your environment you can install python-devel-26 as follows:
$ sudo zypper install python-devel-26Installation
You should have been provided with an RPM file which contains Shiny Server and all of its dependencies (other than R and Shiny). Note that the CentOS 5 RPM of Shiny Server is the one that's compatible with SLES, so know that there's not a problem if you see that branding on your file. You can install this RPM file using zypper. If you have only a link to the RPM file, you can use wget to download the file to the current directory. You can install this RPM file using zypper.
$ sudo zypper install shiny-server-1.4.0.rpmDuring the installation zypper will prompt to ensure that you still want to install even without the libffi dependency. The prompt will look like this:
Problem: nothing provides libffi needed by shiny-server
Solution 1: do not install shiny-server
Solution 2: break shiny-server by ignoring some of its dependencies
Choose from above solutions by number or cancel [1/2/c] (c): 2The libffi dependency is not required on SLES so it is safe to install without it. You should enter "2" (ignore the dependencies) at this prompt and continue with the installation.
This will install Shiny Server into /opt/shiny-server/, with the main executable in /opt/shiny-server/bin/shiny-server and also create a new shiny user. The rest of this guide will document the intricacies of how you can configure and manage Shiny Server. If you're just looking to get up and running quickly, we recommend you look at the Quick Start section in the appendix which will walk you through the process of installing and configuring a Shiny application.
Before Shiny Server can be installed, the Shiny package must be installed in the system library; you typically need sudo privileges to install to this library.
Setup the Server for Secure Package Installation
R packages can be installed securely using an HTTPS CRAN mirror, or insecurely using an HTTP mirror. Beginning with R version 3.2.2, HTTPS is the default preference when installing packages, but older versions of R default to insecure HTTP. You can change this behavior in older versions of R by setting the download.file.method option in your .Rprofile. See R Startup Files for details on where these files are located.
You should add the following line to Rprofile.site to affect how all users install packages, or the ~/.Rprofile file for individual users who will be running Shiny applications in Shiny Server.
For R 3.2
options(download.file.method = "libcurl")For R 3.1 and earlier
options(download.file.method = "wget")You could alternatively use curl instead of wget, if wget is not available on your server.
You'll also want to specify a secure default CRAN mirror in this same file. You can do that using the following code:
local({
r <- getOptions("repos")
r["CRAN"] <- "https://cran.rstudio.com/"
options(repos=r)
})Install The Shiny Package
Shiny Server currently requires Shiny version 0.7.0 or later. The following command will download and install the shiny package from CRAN in the system library.
$ sudo su - -c "R -e \"install.packages('shiny')\""If you have not set a default CRAN repository (as described in the section above) you may need to specify the repos parameter from which to download shiny and its dependencies.
Once this command completes, you can continue with the installation of Shiny Server.
Shiny Server expects that R is available as an executable named R and is in the PATH of the user which you run shiny-server as. Note that on some CentOS systems, the PATH will be overridden by the startup script to /sbin:/usr/sbin:/bin:/usr/bin. On such systems, if R is not available in one of these locations (regardless of the user's PATH), you'll need to adjust the startup script.
To allow Shiny Server to search for R in additional locations, you'll alter the file in /etc/init.d/shiny-server or /etc/init/shiny-server.conf depending on which startup system you're using (as discussed in Stopping and Starting. You can either adjust the PATH variable to include the directory where R will be found, or you can set an environment variable named R to tell Shiny Server exactly where it should look for the executable.
If you choose to adjust the PATH, you can add the directory in which the executable named R is found to the line that defines the PATH environment variable (PATH=/sbin:/usr/sbin:/bin:/usr/bin).
If instead you choose to tell Shiny Server the exact executable to run (which is necessary if the executable is not named R on your system), you'll need to define a new environment variable named R. You can do this by adding a line that looks something like env R=/usr/local/bin/R-3-0-1 for Upstart, or export R=/usr/local/bin/R-3-0-1 for init.d.
The installer will automatically deploy the necessary scripts to ensure that Shiny Server is started automatically on boot. When possible, we use the Upstart system to manage the shiny-server service. If Upstart is not available, we will deploy an init.d script to automatically start and stop the service.
systemd is a management and configuration platform for Linux. The newest versions of most major Linux distributions have adopted systemd as their default init system.
The Shiny Server installer will automatically install a systemd service called shiny-server, which will cause the shiny-server program to be started and stopped automatically when the machine boots up and shuts down. The shiny-server service will also be launched automatically when the installer has successfully installed the program.
To manually start or stop the server, you can use the following commands.
$ sudo systemctl start shiny-server$ sudo systemctl stop shiny-serverYou can restart the server with:
$ sudo systemctl restart shiny-serverThis command will shutdown all running Shiny processes, disconnect all open connections, and re-initialize the server.
If you wish to keep the server and all Shiny processes running without interruption, but reload the configuration, you can use the systemctl command to send a SIGHUP signal:
$ sudo systemctl kill -s HUP --kill-who=main shiny-serverThis will cause the server to re-initialize but will not interrupt the current processes or any of the open connections to the server.
You can check the status of the shiny-server service using:
$ sudo systemctl status shiny-serverAnd finally, you can use the enable/disable commands to control whether Shiny Server should be run automatically at boot time:
$ sudo systemctl enable shiny-server$ sudo systemctl disable shiny-serverUpstart is a system used to automatically start, stop and manage services. The installer will automatically deploy an Upstart script to /etc/init/shiny-server.conf. This script will initialize shiny-server as soon as the network is activated on the machine and stop when the machine is being shut down.
The Upstart script will also ensure that shiny-server is respawned if the process is terminated unexpectedly. However, in the event that there is an issue which will consistently prevent Shiny Server from being able to start (such as a bad configuration file), Upstart will give up on restarting the service after approximately 5 failed attempts within a few seconds. For this reason, you may see multiple repetitions of a bad Shiny Server startup attempt before it transitions to the stopped state.
To start or stop the server, run the following commands, respectively.
$ sudo start shiny-server$ sudo stop shiny-serverTo restart the server you can run:
$ sudo restart shiny-serverThis command will shutdown all running Shiny processes, disconnect all open connections, and re-initialize the server. Note that restart will not reread the Upstart definition at /etc/init/shiny-server.conf. So if you have changed, for instance, some environment variables in that file, you will need to stop and start to have those changes take effect.
If you wish to keep the server and all Shiny processes running without interruption, but reload the configuration, you can use the reload command as in:
$ sudo reload shiny-serverThis will cause the server to re-initialize but will not interrupt the current processes or any of the open connections to the server.
Known Bug: Due to a bug in the version of Upstart which comes with Ubuntu 13.04, reload will not behave as expected on that platform and should not be used.
To check the status or retrieve the Process ID associated with shiny-server, run the following:
$ status shiny-serverOn some older Operating Systems (such as RedHat 5) the Upstart system may not be available. These systems will require the use of a script in /etc/init.d/ to start and manage the shiny-server daemon. This script does not have the capability to automatically restart the shiny-server daemon if it terminates unexpectedly. The installer uses chkconfig to ensure that shiny-server will start automatically on boot.
To start or stop the server, use the following commands, respectively:
$ sudo /sbin/service shiny-server start$ sudo /sbin/service shiny-server stopTo restart the server, you can run:
$ sudo /sbin/service shiny-server restartIf you wish to keep the server and all Shiny processes running without interruption, but reload the configuration, you can use reload:
$ sudo /sbin/service shiny-server reloadThis will cause the server to re-read the configuration file but will not interrupt the current processes and outstanding connections to the server.
To check the status or retrieve the Process ID associated with shiny-server, run the following:
$ /sbin/service shiny-server statusInitially, Shiny Server uses the following configuration file. Some users will find that this configuration meets their needs; others may find it useful to create a custom configuration. Details about each available setting and parameter are available in the Appendix. As a brief introduction, however, the following configuration file will be installed at /etc/shiny-server/shiny-server.conf if it doesn't already exist:
# Define the user we should use when spawning R Shiny processes
run_as shiny;
# Define a top-level server which will listen on a port
server {
# Instruct this server to listen on port 3838
listen 3838;
# Define the location available at the base URL
location / {
#### PRO ONLY ####
# Only up tp 20 connections per Shiny process and at most 3 Shiny processes
# per application. Proactively spawn a new process when our processes reach
# 90% capacity.
utilization_scheduler 20 .9 3;
#### END PRO ONLY ####
# Run this location in 'site_dir' mode, which hosts the entire directory
# tree at '/srv/shiny-server'
site_dir /srv/shiny-server;
# Define where we should put the log files for this location
log_dir /var/log/shiny-server;
# Should we list the contents of a (non-Shiny-App) directory when the user
# visits the corresponding URL?
directory_index on;
}
}Lines beginning with a # are treated as comments and not parsed when configuring the server. Shiny Server can be configured to host multiple servers on different ports or hostnames. Each server can have locations which are capable of serving Shiny Applications and potentially static assets, as well. Individual applications can also override the settings applied to their parent location. These concepts are explained in further detail in the Server Hierarchy section. The default configuration above will create a single server listening on port 3838, serving any application contained within /srv/shiny-server/ at the root URL (/). Each possible setting in the configuration file is explained in the Appendix.
Most users will want to customize the configuration to meet their needs. The server will load its configuration from a file stored at /etc/shiny-server/shiny-server.conf; it is in this location that you should customize your Shiny Server configuration.
Detailed descriptions of all available parameters are available in the appendix, but it is important to understand the overall hierarchy of the Shiny Server configuration file when editing the file.
The server setting defines an HTTP server which will listen on a port/IP address combination. For example, the following lines:
server {
listen 80;
}define a server that would listen on port 80. A server can also define a server_name to limit the virtual hostnames on which it listens, as described in the Virtual Hosts section.
The location setting is defined within a server and defines how a particular URL path should be served. For instance, the following settings:
server {
...
# Define the location '/specialApp'
location /specialApp {
# Run this location in 'app_dir' mode, which will host a single Shiny
# Application available at '/srv/shiny-server/myApp'
app_dir /srv/shiny-server/myApp
}
# Define the location '/otherApps'
location /otherApps {
# Run this location in 'site_dir' mode, which hosts the entire directory
# tree at '/srv/shiny-server/apps'
site_dir /srv/shiny-server/apps;
}
...
}would define two locations, one which serves (potentially) a multitude of applications at the URL /otherApps/, and another which serves a single application at the URL /specialApp/. The various hosting models which can be applied to a location are described in the section on Hosting Models.
location directives can also be nested to provide more granular settings for a particular sub-location. For instance, if you used Google Analytics but the Finance department wanted to use its own Google Analytics ID for their finance directory, you could accomplish that with a configuration like:
server {
...
# Define the '/depts' location
location /depts {
# Host a directory of applications
site_dir /srv/departmentApps;
# Provide a default/global GAID
google_analytics_id "UA-12345-1";
# Define the '/finance' location.
# Corresponds to the URL '/depts/finance', and the filesystem path
# '/srv/departmentApps/finance' as defined by the parent location.
location /finance {
# Provide a custom GAID for only this sub-location
google_analytics_id "UA-54321-9";
}
}
...Note that the nested location's path is relative to the parent location's. Any directive that can be used for a location can be used in a nested location and will override the value specified in the parent, if any. If not overridden, the settings will be inherited by sub-locations from their parent locations.
The
applicationsetting has been deprecated and removed from Shiny Server as of version 0.4.2.
See How Do I Translate My 'application' Settings to Nested 'location's? for help migrating.
run_asUnderstanding which user will execute the R Shiny processes is important for a variety of reasons. For one, the paths in which R will look for packages (.libPaths()) are often user-dependent. In order to ensure that the libraries required to run a Shiny application are installed, you must first understand which user will be running the application. Additionally, directories will likely have restrictions regarding which users are able to read or write in them. The server should be configured in such a way that the user running the Shiny applications has the minimal privileges to do the work required by those applications.
locations configured with user_apps will be executed as the user in whose home directory the application was found. For locations configured with site_dir, user_dirs, and app_dir, the run_as setting will be used to determine which user should spawn the R Shiny processes. This setting can be configured globally, or for a particular server or location. For example, the following configuration:
location / {
run_as tim;
}would execute all applications contained within this scope as the user tim with all of tim's relevant .libPaths.
Additionally, R processes are spawned using the Bash login shell. This means that prior to the execution of the R session the Bash shell will read and execute commands from this file if it exists:
/etc/profileAfter reading that file, it looks for the following files and reads and executes commands from the first one that exists and is readable (it’s important to note that only one of these files will be read and executed):
~/.bash_profile
~/.bash_login
~/.profileSo in the above configuration example, any environment variables defined in /etc/profile or /home/tim/.bash_profile (assuming tim's home directory was in the standard location) would be available to the R process, since Shiny Server is configured to run applications as the user named tim.
:HOME_USER::HOME_USER: is a special instance of a run_as user. When combined with the user_dirs hosting model (described in the section entitled Host Per-User Application Directories), this setting will instruct Shiny Server to run the process as the user in whose home directory the application exists. For instance, an application stored in /home/jim/ShinyApps/app1 would run as jim, whereas an app stored in /home/kelly/ShinyApps/app1 would run as kelly.
Because this username is "special", it may make sense to provide an additional username as a "fallback" user. For instance, in the following configuration:
run_as :HOME_USER: shiny;
...
location /users {
user_dirs;
}
location /apps {
site_dir /srv/shiny-server;
log_dir /var/log/shiny-server;
directory_index on;
}all of the user_dirs applications hosted in /users would run as :HOME_USER: (the user in whose home directory the application exists), since that's the highest-priority run_as user. Because :HOME_USER: is only meaningful to the user_dirs hosting model, and not to site_dir, the applications hosted in /apps will not run as :HOME_USER: but as whichever user comes next in the list -- in this case, as shiny.
Of course, you could also accomplish this same effect with the following arrangement:
location /users {
run_as :HOME_USER:;
user_dirs;
}
location /apps {
run_as shiny;
site_dir /srv/shiny-server;
log_dir /var/log/shiny-server;
directory_index on;
}As described in Host Per-User Application Directories, user_apps and user_dirs differ only in how they behave with respect to the run_as setting. user_apps will always host the apps as if run_as were set to :HOME_USER:, regardless of how run_as is actually set. user_dirs, on the other hand, will respect the run_as configuration.
Aside from spawning R Shiny processes as particular users, the shiny-server process itself can be configured to run as different users to control its privileges. There are multiple scenarios in which Shiny Server would need to be run as root:
user_apps or user_dirs is enabled for any location. In order to host applications as various users, Shiny Server must have root privileges.run_as to spawn applications as multiple different users.auth_pam to leverage PAM authentication. (Pro only)auth_google and store your client secret in a file. (Pro only)By default, the shiny-server process will be started as the root user, then will spawn R processes according to the corresponding run_as setting. You can, however, run the shiny-server process as a non-privileged user such as the shiny user if none of the limitations above are violated.
In the global configuration file, the allow_app_override setting can be specified to enable local app configurations. If present, this setting enables owners of Shiny applications to customize the properties of their own applications using a file named .shiny_app.conf. This file can be placed within an application directory (alongside the server.R and ui.R files) and can contain settings which configure how Shiny Server should manage the application.
This behavior is controlled by the allow_app_override setting which is disabled by default. In order to enable local application configurations, you can add to your configuration file allow_app_override true; (or just allow_app_override; for short).
Server administrators should be mindful of the fact that allowing application owners to specify their own scheduler parmeters has potential performance implications, as an application owner could enable his or her application to consume more resources than is desired. It is thus recommended that write privileges on the .shiny_app.conf files be granted judiciously in the underlying filesystem.
There are currently four different methods of configuring a location, three of which serve Shiny applications. These three are described below; see the following section on Redirecting to learn about a fourth mode.
A location which uses site_dir will host an entire directory tree -- both Shiny Apps and static assets. This is the location used to serve an asset or application in /srv/shiny-server/ in the default configuration that ships with Shiny Server.
# Define the location '/'
location / {
site_dir /srv/shiny-server/
}The above configuration would instruct Shiny Server to make the /srv/shiny-server/ directory available at the base URL. Any Shiny applications stored in this directory (or any subdirectory), along with any static assets (including images, data, JavaScript/CSS files, etc.) will be made available at the corresponding URL. For example, see the following directory tree:
+---/srv/shiny-server
| +---shinyApp1
| +---server.R
| +---ui.R
| +---shinyApp2
| +---server.R
| +---ui.R
| +---assets
| +---style.css
| +---script.jsIf this server were available at http://server.com, the location settings above would make the following (along with any other file in the tree) publicly available to the user.
| URL | Definition |
|---|---|
http://server.com/shinyApp1 |
Serve the Shiny App defined in 'shinyApp1' |
http://server.com/shinyApp2 |
Serve the Shiny App defined in 'shinyApp2' |
http://server.com/assets/style.css |
Serve this static CSS file |
http://server.com/assets/script.js |
Serve this static JS file |
A location configured to use app_dir will attempt to serve a single application hosted at the given directory. For instance,
# Define the location '/specialApp'
location /specialApp {
app_dir /srv/shiny-server/myApp;
}will configure the location responsible for the path /specialApp to use this app_dir router which serves a single application stored in the directory /srv/shiny-server/myApp. This configuration would presume a server.R file (and corresponding ui.R file) would be available at /srv/shiny-server/myApp/server.R. If so, the application saved there would be available at a URL like http://server.com/specialApp.
A location configured to use user_dirs will allow users on the system to create and manage their own Shiny applications available in their home directories. This directive will host any application stored in an eligible user's ~/ShinyApps directory publicly at a URL prefaced by their username.
This privilege can be restricted only to users of particular groups using the members_of restriction. For instance, the following configuration:
run_as :HOME_USER:;
# Define the root location
location / {
user_dirs;
# Only allow members of the 'shinyUsers' group to host personal applications.
members_of shinyUsers;
}will -- for any user who is a member of the shinyUsers group -- publicly host any Shiny application available in the user's ~/ShinyApps directory. For instance, if tina is a user on this system and is also a member of the shinyUsers group, any application stored in /home/tina/ShinyApps/, such as the shinyApp1 application, would be available on this server at a URL like http://server.com/tina/shinyApp1, assuming /home/tina was tina's home directory.
The user_dirs setting is intended to ultimately replace the user_apps setting. The two models are very similar but differ in how the handle run_as settings. user_apps ignores the run_as setting and always runs applications as the user in whose home directory they exist. user_dirs, on the other hand, will respect the run_as setting. You can use the special run_as user :HOME_USER: to make user_dirs operate the same way as user_apps does; thus, the two following configurations would be identical:
location / {
user_apps;
}location / {
run_as :HOME_USER:;
user_dirs;
}Note that, while Shiny Server supports the ability to run in user_dirs as a single user, this may require some tweaking to make function correctly on your server. For instance, the following configuration:
location / {
run_as shiny;
user_dirs;
}would indeed attempt to start the applications housed in your users' home directories as the shiny user, but many distributions, by default, restrict access to users' private /home directories, meaning that the shiny user would not be able to read or write to the directories it needs to in order to run these applications properly.
The final mode in which a location can operate is to redirect to another URL. Such locations will immediately send a response to the client informing them of the URL to which they should redirect and the status code that should be used when informing the client of the redirection. Typically, a redirect will use the 301 status code for a permanent redirect, or a 302 status code for a temporary redirect. The final option when configuring a location for redirection is whether or not it should use exact matching. If a redirecting location is configured to use exact matching, only requests for that exact URL will be redirected. If not, any requests for that URL path or any subpath of that URL will be redirected. For example,
# Define a location at the base URL of this 'server'
location / {
# Redirect traffic from '/shinyApp1/' to 'http://server.com' temporarily.
location /shinyApp1 {
redirect "http://server.com" 302 true;
}
}will redirect any requests for the exact path /shinyApp1 to http://server.com temporarily.
The server_name setting allows Shiny Server to route incoming requests to a particular server element based on the hostname of the request. This will serve as an additional level of filtering on incoming traffic. Bear in mind that traffic must be destined for this server (i.e. traffic which was bound for the IP address and port on which this server was listening) in order to even be evaluated for a matching hostname.
The example below may clarify the configuration
server {
# Instruct this server to listen to port 80
listen 80;
# Only accept requests for the hostname 'server1.com'
server_name server1.com;
# Define the location for this server.
location / {
site_dir /srv/shiny-server1;
log_dir /var/log/shiny-server1;
}
}
server {
# Instruct this server to listen to port 80
listen 80;
# Only accept requests for the hostname 'server2.com'
server_name server2.com;
# Define the location for this server.
location / {
site_dir /srv/shiny-server2;
log_dir /var/log/shiny-server2;
}
}This example presupposes that, on this network, the domains server1.com and server2.com both resolve to the same IP address. In the configuration above, we first create a server that listens on port 80 and will only accept traffic whose hostname matches server1.com. We then configure a server which will also listen on port 80 and require that it only accept traffic whose hostname equals server2.com.
This configuration would allow an application stored in /srv/shiny-server1/shinyApp to be accessible at http://server1.com/shinyApp and an application stored in /srv/shiny-server2/shinyApp to be accessible at http://server2.com/shinyApp.
Shiny Server can utilize custom templates when generating static pages such as directory indexes and error pages. This feature is controlled using the template_dir directive and can be applied globally, or to a particular server or location.
To utilize this feature, you'll need a directory in which you'll store your templates. In this example, we'll assume you're using /etc/shiny-server/templates/. Inside this directory, you'll place the handlebars-enabled HTML templates for your pages.
Shiny Server will attempt to find a specific page to accommodate the current need -- for instance, if it encountered a 404 error, it will first look to see if you provided a specific template for handling 404 errors in the specified directory (error-404.html). If it doesn't find this file, it will go one step backwards to see if you provide a generic error template (error.html). If it can't find a suitable template in your template directory, it will fall back to use the provided templates that come with Shiny Server (and are stored in /opt/shiny-server/templates).
As you may have noticed already, Shiny Server uses a hyphen-delimited hierarchy which progresses from broadest to narrowest. So all error pages start with error. But the file name for a 404 error page would add an additional element (404) following a hyphen: error-404. All files are expected to use the .html extension.
The tables below describe the page templates that can be defined in Shiny Server:
| Template Name | Description |
|---|---|
| error-403 | Client is forbidden from accessing this page. Or, in Shiny Server Pro, that the user is signed in but does not have permissions to view this application. |
| error-404 | Page not found |
| error-500 | General server error |
| error-503-users | The application has exceeded its maximum # of users |
| error-503-license | (Pro Only) You have exceeded the number of concurrent users allotted for your license. |
| directoryIndex | Shown when directory_index is enabled for a location and the user visits the base URL. |
| login | (Pro Only) Used to render the login page. |
Again, any of the template names that have hyphens in them can be generalized by trimming off the hyphen and subsequent word(s). So a file named error-503.html could be used as the template for both error-503-users pages, as well as error-503-license pages. More generally, a single template can be used for all errors by naming it error.html. If a more specific template doesn't exist, this page would be used when generating any type of error page.
We recommend starting with the existing templates then modifying them to create your own branding. To do this, copy the relevant HTML files out of /opt/shiny-server/templates/ into your template directory (for example, /etc/shiny-server/templates/). To create a custom error page, execute:
$ mkdir /etc/shiny-server/templates/
$ cp /opt/shiny-server/templates/error.html /etc/shiny-server/templates/Now open the template in your preferred text editor and modify it. Initially, leave the overall structure intact, but add some language at the top of the page (immediately under the line containing <h1>{{title}}</h1>) or add some new CSS rules then save the file.
Now instruct Shiny Server to use this new template in your configuration by adding the line:
template_dir /etc/shiny-server/templates;at the top/bottom of the file so it applies globally. Of course, you can later specify another template_dir for particular locations.
When you restart the server and access an error page. (Try accessing a hidden file like http://server.com:3838/.hidden, where server.com is the domain name or IP address of your server, which should use the error-403 or error template.) You should see your new text or CSS styling on the page that is loaded. Likewise, you can copy the directoryIndex.html template or, for Shiny Server Pro, the login.html template to your custom directory and begin customizing.
For performance reasons, templates are cached in memory once they're loaded. Thus, you will find that changes to your template may not be immediately visible when you refresh the page. To empty the cache to force Shiny Server to load in the new changes to your template, you can either restart or reload the server (see the section on Stopping and Starting).
Finally, note that these templates currently only apply for HTML pages that are generated by Shiny Server. An HTML page generated by the Shiny package will not have custom templates applied at this time. Currently, this is most visible with 404 errors. If you access a URL which Shiny Server cannot direct to a Shiny application (for instance, http://server.com:3838/flargdarg, where server.com is the domain name or IP address of your server), you will see a Shiny-Server-generated 404 error page which has custom templates applied (assuming this server is configured to have a custom error-404.html or error.html template). However, if you were to access a file that does not exist in a valid application, you would see an un-styled 404 page that did not leverage your custom template. For instance, if you have an application deployed at http://server.com:3838/myApp and you attempt to access http://server.com:3838/myApp/flargDarg, the request would be sent to Shiny which would then look for this file and, if it isn't found, would return a 404 page. Shiny Server would pass this response back directly to the client, as it wasn't generated by Shiny Server. We will be reviewing this architecture in future versions -- please let us know if you find that the current organization inhibits your workflow.
All information related to Shiny Server, rather than a particular Shiny application, is logged in the global system log stored in /var/log/shiny-server.log. This log should be checked often to ensure Shiny Server is performing as expected. Any errors and warnings which Shiny Server needs to communicate will be written here.
If logrotate is available when Shiny Server is installed, a logrotate configuration will be installed. The default configuration is to rotate the logfile when it exceeds 1MB. The old log file will be compressed and stored alongside the original log file with a .1.gz extension (then .2.gz, etc.). Up to twelve archived log files will be maintained; upon the 13th log rotation the oldest log file will be deleted.
For logs related to individual Shiny Applications, see the section on Logging and Analytics.
An access log can be configured globally using the acces_log parameter. This log is not enabled by default. This setting controls the location of the access log as well as the format used. The access log can be useful to audit the security and activity taking place on your Shiny Server installation. These logs can be audited manually or automatically to inspect how often various resources are being accessed, or by whom they are being accessed (using the originating IP address). Currently, one access log is created for the entire Shiny Server process; all Shiny applications share this access log.
The access logs will be written using the Connect logging libraries, so additional details can be found in their documentation in the "Formats" section. In brief, there are four pre-defined logging formats for access logs specified in the documentation referenced above:
default ':remote-addr - - [:date] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"'short ':remote-addr - :method :url HTTP/:http-version :status :res[content-length] - :response-time ms'tiny ':method :url :status :res[content-length] - :response-time ms'dev concise output colored by response status for development useFor example, the following would configure an access log that uses the tiny format:
access_log /var/log/shiny-server/access.log tiny;
server {
...We strive to expose most settings through the configuration file described previously. However, there are some settings that we don't include in the configuration file which some users may still wish to change. Where possible, we'll allow users to configure these settings using environment variables. Some of these environment variables will later be promoted to configuration directives, but will be documented here until that time.
Typically, it is best to define these environment variables in the startup script used to run Shiny Server. This varies depending on what Linux distribution and version you are running.
File to change:
/etc/systemd/system/shiny-server.serviceHow to define the environment variable:
[Service]
Environment="SHINY_LOG_LEVEL=TRACE"Commands to run for the changes to take effect:
$ sudo systemctl stop shiny-server
$ sudo systemctl daemon-reload
$ sudo systemctl start shiny-serverFile to change:
/etc/init/shiny-server.confHow to define the environment variable:
env SHINY_LOG_LEVEL=TRACECommands to run for the changes to take effect:
$ sudo restart shiny-serverFile to change:
/etc/init.d/shiny-serverHow to define the environment variable:
export SHINY_LOG_LEVEL=TRACECommands to run for the changes to take effect:
$ sudo /sbin/service shiny-server restartSHINY_LOG_LEVELDefines the verbosity of logging which will be used by Shiny Server. Valid options -- in level of increasing verbosity -- are TRACE, DEBUG, INFO, WARN, and ERROR. More verbose levels of logging (such as TRACE) may be helpful when debugging an issue or trying to understand exactly what Shiny Server is doing, but will likely be far too much information for a system with even moderate load.
The default if this environment variable is not found is to use INFO.
RDefines the path to the R executable which should be used when running Shiny. Systems which have multiple versions of R installed, or don't wish to place R on the path before starting Shiny Server can override this setting to point to a particular version of R.
Note that, for any location with a configured [r_path] in the configuration file, this environment variable will not take effect. If no environment variable is found, Shiny Server will expect an executable named R to be on the path.
A scheduler is responsible for fulfilling incoming requests to a particular application. Each version of an application (see below) will have its own associated scheduler. Each scheduler can have different properties to control things like how many concurrent connections it should accept.
A scheduler can be specified at many locations in the configuration file and will be inherited to inner blocks. For instance, a scheduler definition found in a server block will be applied to every location in that server, unless overridden.
Some changes you make to the code, assets, or environment of an application will require the application's R processes to be restarted for the changes to take effect. These include upgrades to packages that are used by the application, changes to .Renviron/.Rprofile or other R source files, or modifications to data files that are read only at startup time.
(Fortunately, Shiny applications generally do not need to be restarted when changes to ui.R or server.R are made, as Shiny will check for changes to these files on page load.)
An application can be restarted by altering the "modified time" on a file named restart.txt in the application's directory. This can most easily be done using the touch utility as in touch restart.txt which will update the modified timestamp on this file to the current time. Upon the next new connection to the application, Shiny Server will spawn a new R process to run the "new" (restarted) Shiny Application for this and future users. When this occurs, the old processes will remain unaltered, and open connections will remain active and valid until the last connection closes itself.
This can cause unintuitive consequences regarding the number of processes that may be running for a given application. Even if using a single-process Simple Scheduler for an application, it is possible that there would be multiple R processes associated with this application, each corresponding to a separate restart timestamp. This behavior is likely to change in future versions of Shiny Server.
The Simple Scheduler is the only scheduler available in the Open Source edition of Shiny Server. It associates a single R process with a single Shiny application. This scheduler accepts a single parameter which specifies the maximum number of concurrent sessions. Once this number is reached, users attempting to create a new session on this application will receive a 503 error page.
# Define a new location at the base URL
location / {
# Define the scheduler to use for this location
simple_scheduler 15;
...
}In this example, the location defined at the base URL in this server will be configured to use the Simple Scheduler and to limit each application to a maximum of 15 simultaneous connections -- meaning that if there are 15 active connections on the application when a user attempts to visit this application, that user will receive a 503 error page. When one of the 15 active connections is disconnected, one new "seat" will be available for another user to connect to the application.
In addition to serving traditional Shiny applications out of a directory (a server.R file and an associated UI), Shiny Server now supports interactive R Markdown documents. If a hosted directory does not include a server.R file, Shiny Server will look to see if it contains any .Rmd files. If so, Shiny Server will host that directory in "R Markdown" mode using rmarkdown::run.
Particular Rmd files can be accessed by referencing their full path including the filename, e.g. http://myserver.org/mydocs/hello.Rmd. If a request is made to a directory rather than a particular Rmd file, Shiny Server will attempt to serve the file index.Rmd. If that file does not exist, the user will get an error alerting them that the file is not available.
Each Shiny Application has two timeouts associated with it:
app_init_timeout -- Describes the amount of time (in seconds) to wait for an application to start. After this many seconds if the R process still has not become responsive, it will be deemed an unsuccessful startup and the connection will be closed.app_idle_timeout -- Defines the amount of time (in seconds) an R process with no active connections should remain open. After the last connection disconnects from an R process, this timer will start and, after the specified number of seconds, if no new connections have been created, the R process will be killed.Typically, these two parameters will be correlated. Shiny Applications which involve little processing to start (therefore have a small app_init_timeout) can often be closed with minimal concern (thus would have a small app_idle_timeout). Conversely, applications which require a substantial amount of data to be loaded on startup may merit a longer app_init_timeout to give the data time to load, and a longer app_idle_timeout as the task of spawning a new process is more expensive and should be minimized.
Error logs are created for each R Shiny process separately. For locations configured to use user_apps or user_dirs, these logs are created in each user's ~/ShinyApps/log/ directory. For locations configured with app_dir or site_dir, the directory in which these logs are created is managed by the log_dir setting, which can be specified globally, for a particular server, or for a particular location. By default, these logs will be located at /var/log/shiny-server/. To change these locations, the log_dir can be specified in the following way:
location / {
log_dir /var/log/shiny-server/;
}The log files will be created in the following format:
<application directory name>-YYYMMDD-HHmmss-<port number or socket ID>.logLog files will be created for each R process when it is started. However, if a process closes successfully, the error log associated with that process will be automatically deleted. The only error log files that will remain on disk are those associated with R processes that did not exit as expected.
If you're looking for log messages related to Shiny Server itself -- rather than individual Shiny applications -- see the section on the Server Log.
Shiny Server is capable of automatically inserting the necessary JavaScript code to enable Google Analytics tracking globally or for a particular server or location. This is managed by the google_analytics_id setting which can be used as follows:
location / {
google_analytics_id UA-12345-1;
}The reactivity log is a great browser-based tool for analyzing and debugging reactive dependencies in a Shiny Application. We strongly recommend that you read the Overview of Reactivity in the Shiny tutorial to get the most out of the reactivity log. The symbols and representations introduced in that article are reused in the log. This tool should not be used in a production environment, as it exposes details that should not be publicly available. Many application authors find it to be a useful tool to use locally, however.
Currently, reactivity logs are maintained for an entire R process. Therefore, it should be used in a fresh R session in which only one Shiny application is active. To enable the reactivity log, run the command options(shiny.reactlog=TRUE) before running your application. Once you've started your application and are viewing it in a browser, you can use Ctrl+F3 (or Command+F3 for Mac users) to view the reactivity log. This visualization creates a snapshot of all reactive activity that had occurred up to the moment it was created. If you want to view the reactive activity that has occurred since opening the reactivity log, you'll need to refresh the browser.
The showReactLog() function exposes this functionality from within R and can be used outside of strictly Shiny contexts to generate a static HTML file visualizing reactivity. You can see the full documentation using ?showReactLog in R.
As the reactivity log exposes the architecture and some of the code behind your application, it would likely be unwise to enable this feature in a production environment. Unless explicitly enabled by the user, Shiny Server will not enable this functionality. We recomend using the reactivity log in a local R process not managed by Shiny Server.
Shiny Server can use a wide variety of techniques to keep the data in the web browser synchronized. The preferred technique, and the one most widely used, is the use of WebSockets. However, if WebSockets are not supported -- either by some intermediate network between Shiny Server and your client or by your client's web browser -- then a fallback protocol will be used. In total, Shiny Server provides nine different methods of connecting to the server in real-time. In order of preference, they are:
Each of these will be tried by the client in order until a successful connection to Shiny Server. If you would like to omit one or more of these protocols from the list for whatever reason, you can currently do so only from the client (we hope to make a server-side configuration available in a future release of Shiny Server).
To change the available protocols from the client, you can open any Shiny Application and press the keyboard shortcut: Ctrl+Alt+Shift+A (or, from a Mac: control+option+shift+A). This will bring up a window that will allow you to select or deselect any of the above protocols. After confirming your changes these settings will be saved in your browser for future visits to this server. These settings will take effect upon loading any Shiny application hosted on this domain and will last until you explicitly change them again; they will only have an effect on the browser in which this action was performed.
Shiny Server uses SockJS to facilitate communication between the browser and the server. On most networks, SockJS will be able to resolve a functioning protocol that will allow it to reliably communicate between the browser and Shiny Server. Some environments, however, will perform some sort of filtering or proxying that hinders one or more of the available protocols. Older networking equipment will likely not function well with WebSockets, for instance.
Most users will not need to worry about what protocol their network will support, as SockJS will gracefully determine the best protocol when trying to establish the connection. However, some environments have found consistent problems with having particular protocols enabled and find that a particular protocol or set of protocols are most reiable in their environment. In this case, you can use the disable_protocols setting to disable any of the available protocols.
For instance, if you find that WebSockets and XDR polling are problematic on your networking equipment, you could add the following configuration to disable them:
disable_protocols websocket xdr-polling;The protocol names to be used when disabling are as follows:
websocket
xdr-streaming
xhr-streaming
iframe-eventsource
iframe-htmlfile
xdr-polling
xhr-polling
iframe-xhr-polling
jsonp-pollingShiny Server Professional supports integration with Kerberos for seamless authentication to other applications via Kerberos tickets. To enable this feature you need to have the following defined in your /etc/shiny-server/shiny-server.conf file:
run_as :AUTH_USER:;
auth_pam true;
pam_sessions_profile shiny-session;This assumes you are using a file named shiny-session for the pam.d session profile, but the name could be anything as long as it matches your actual filename.
You also need to customize your Shiny Server pam.d files: shiny-server and shiny-session. We provide a very simple example of these files here that uses pam_krb5.so as a guide.
/etc/pam.d/shiny-server
auth sufficient pam_krb5.so
account required pam_krb5.so
session requisite pam_krb5.so /etc/pam.d/shiny-session
auth required pam_krb5.so
account [default=bad success=ok user_unknown=ignore] pam_krb5.so
password sufficient pam_krb5.so use_authtok
session requisite pam_krb5.so We recommend reading through the relevant sections of this guide to gain a complete understanding of how to operate Shiny Server. If you're just looking to get running quickly, you can follow one of the guides below.
All of the guides will help you customize your Shiny Server configuration file which will be stored at /etc/shiny-server/shiny-server.conf. By altering this file, you can control exactly how Shiny Server runs.
The following guides are available:
/etc/shiny-server/shiny-server.conf. This guide will show you how to serve multiple applications from a single directory on disk -- /srv/shiny-server/. If you're not sure where to start, we recommend this guide.Shiny Server is configured by a file stored at /etc/shiny-server/shiny-server.conf. To more conveniently use this Quick Start guide, we provide a convenient executable in /opt/shiny-server/bin/deploy-example that can copy the example configuration file associated with this Quick Start to that location and install a directory of example applications. Be sure to backup your current configuration file if you've done any customizing, then run the following command:
sudo /opt/shiny-server/bin/deploy-example defaultThis configuration expects your Shiny applications to be hosted in /srv/shiny-server/. The installer will also place one sample application in /srv/shiny-server/sample-apps/hello/.
By default, Shiny Server listens on port 3838, so the default application will be available at http://<server-address>:3838/sample-apps/hello/.
If you wanted to change the port or the directory Shiny Server uses, you would adjust the configuration file. To begin customizing your server, open /etc/shiny-server/shiny-server.conf in your preferred text editor and modify the line which says listen 3838. This is the line that instructs your server to listen to port 3838 -- change it to another port such as 12345 and save the file. You'll need to restart Shiny Server to make it aware of the new configuration file. The Stopping and Starting section explains this in more detail. For now, you'll run this command if you're on a distribution which supports Upstart (most recent distributions, including Ubuntu 12 and later and CentOS 6):
sudo restart shiny-serverIf you're on an older system that relies on init.d (such as CentOS 5), you'll use the following command instead:
sudo /sbin/service shiny-server restartYou should now find that Shiny Server is no longer running on port 3838, but is on whichever new port you selected.
Some administrators of Shiny Server would prefer to give users -- or some trusted subgroup of users -- the ability to manage and host their own Shiny applications. This allows users to work directly with their applications rather than requiring an administrator to deploy and update applications on their behalf. This guide will document how to create such an environment using the user_dirs directive documented in the section named Host Per-User Application Directories.
To more conveniently use this Quick Start guide, we provide a convenient executable in /opt/shiny-server/bin/deploy-example that can configure Shiny Server to use the example configuration file associated with this guide (by placing it in /etc/shiny-server/shiny-server.conf). It will also install a directory of example applications. Be sure to backup your current configuration file if you've done any customizing, then run the following command:
sudo /opt/shiny-server/bin/deploy-example user-dirsThis configuration enables all users on the system to host their own applications by creating a ShinyApps directory in their home directory; you can always alter the configuration file later to tailor it to meet your needs. You can deploy an application under your username by copying an example that comes with Shiny Server into your own ShinyApps directory. To do this, copy that entire /opt/shiny-server/samples/sample-apps/hello/ directory into ~/ShinyApps using the following command:
mkdir ~/ShinyApps
sudo cp -R /opt/shiny-server/samples/sample-apps/hello ~/ShinyApps/If that command succeeds, you've successfully installed a user_dirs Shiny application!
By default, Shiny Server listens on port 3838, so your new application will be available at http://<server-address>:3838/<your_username>/hello where <your_username> is your Linux username.
If you wanted to restrict the privilege of running Shiny applications to a particular set of users on your system, you can uncomment the members_of line in the configuration file. You can then specify the Linux group name of which a user must be a member before he or she would be allowed to host Shiny applications.
This guide will show how to run Shiny Server on multiple ports simultaneously and will also show how to run a single server with multiple locations.
To more conveniently use this Quick Start guide, we provide a convenient executable in /opt/shiny-server/bin/deploy-example that can configure Shiny Server to use the example configuration file associated with this guide (by placing it in /etc/shiny-server/shiny-server.conf). It will also install a directory of example applications. Be sure to backup your current configuration file if you've done any customizing, then run the following command:
sudo /opt/shiny-server/bin/deploy-example multi-serverThis configuration will run two servers: one on port 3838, and one on port 4949. As you can see in the configuration file, a variety of different locations are defined with different hosting models.
The server running on port 3838 defines two locations. The first for the URL /users which makes user applications available using the user_dirs hosting model as documented in the section entitled Host Per-User Application Directories. The second location is at the URL /example1 and hosts a single application which should be stored in /srv/shiny-server/sample-apps/hello/. An application is provided here during installation.
However you'll want to copy that application to your home directory, as well, so you have something to view in the /users location. You can copy that application to your home directory with the following commands:
# Copy to your home directory's 'ShinyApps' folder
mkdir ~/ShinyApps
cp -R /srv/shiny-server/sample-apps/hello ~/ShinyApps/You should now be able to access applications in a variety of ways:
user_dirs location at /users hosting your personal applications. You can access the one deployed earlier at a URL like http://<server-address>:3838/users/<your_username>/hello where <your_username> is your Linux username./example1 location. So the URL like http://<server-address>:3838/example1 should point you to the same example./srv/shiny-server. You can access one that comes with Shiny Server at a URL like http://<server-address>:4949/sample-apps/hello which, coincidentally, should point you to the same application you just loaded a moment ago.Listed below are all the directives that are supported in Shiny Server config files.
Applies to indicates the kind of parent scope that this directive normally appears inside.
Inheritable means that you can put this directive at a higher level in the hierarchy and it will be inherited by any children to which it might apply. Inherited directives can be overridden by using the directive again in a child scope.
The user the app should be run as. This user should have the minimal amount of privileges necessary to successfully run the application (i.e. read-only access to the Shiny application directory). Note that this directive cannot be used with user_apps, as user_apps always run as the user who owns the application.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| users | String | multiple | The username that should be used to run the app. If using home_dirs, this can also be the special keyword :HOME_USER: which will instruct home_dirs to run as the user in whose home directory the application exists. If using a special keyword like :HOME_USER:, you can specify additional usernames afterwards which will be used when this directive is applied to hosting models other than home_dirs. |
The file path of the HTTP access log.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| path | String | required | The file path where the access log should be written | |
| format | String | optional | The log file format; see Connect documentation under "Formats" | default |
Top-level
Yes
Declares an HTTP server. You need one of these for each port/IP address combination this Shiny Server instance should listen on.
This directive has no parameters.
Top-level
Yes
listen, server_name
Directs the enclosing server scope to listen on the specified port/IP address combination.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| port | Integer | required | Port to listen on | |
| host | String | optional | IPv4 address to listen on (* or 0.0.0.0 for all); hostnames are not currently allowed, please use raw IPv4 address only |
* |
server
Yes
Directs the enclosing server scope to only honor requests that have the given host headers (i.e. virtual hosts).
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| names | String | multiple | The virtual hostname(s) to bind this server to |
server
Yes
Creates a scope that configures the given URL as a website (site_dir), specific application (app_dir), autouser root (user_apps), autouser root with run_as support (user_dirs), or redirect to a different URL (redirect).
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| path | String | required | The request path that this location should match |
server, location
Yes
run_as, location, site_dir, directory_index, user_apps, user_dirs, app_dir, redirect, log_dir, members_of, google_analytics_id, application, template_dir
Configures the enclosing location scope to be a website that can contain both Shiny applications and unrelated static assets in a single directory tree.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| rootPath | String | required | The path to the root directory of the website |
location
Yes
When enabled, if a directory is requested by the client and an index.html file is not present, a list of the directory contents is created automatically and returned to the client. If this directive is not present in a custom config file, the default behavior is to disable directory indexes. However, it is enabled if no config file is present at all (in other words, the default config file has it enabled).
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| enabled | Boolean | required | Whether directory contents should automatically displayed |
DEREPCATED! This directive has been deprecated in favor of user_dirs, which offers more flexibility with regards to the run_as configuration. Configures the enclosing location scope to be an autouser root, meaning that applications will be served up from users' ~/ShinyApps directories and all Shiny processes will run as the user in whose directory the application is found.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| enabled | Boolean | optional | Whether this location should serve up all users' ~/ShinyApps directories | true |
location
Yes
Configures the enclosing location scope to be an autouser root, meaning that applications will be served up from users' ~/ShinyApps directories. This directive does respect an affiliated run_as setting, meaning that the applications will be executed as whichever user is configured in the applicable run_as setting. Note that many distributions, by default, will prohibit users from being able to access each other's home directories.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| enabled | Boolean | optional | Whether this location should serve up all users' ~/ShinyApps directories | true |
location
Yes
Configures the enclosing location scope to serve up the specified Shiny application.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| path | String | required | The path to the Shiny application directory |
location
Yes
Configures the enclosing location to redirect all requests to the specified URL.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| url | String | required | The URL (or base URL) to redirect to | |
| statusCode | Integer | optional | The status code to send with the response (usually 301 for permanent redirects or 302 for temporary redirects) | 302 |
| exact | Boolean | optional | Whether to match on the URL exactly; if false, any subpaths will match as well | true |
location
Yes
Directs the application to write error logs to the specified directory. Only applies to location scopes that are configured with app_dir or site_dir, as user_apps (autouser) always writes error logs to ~/ShinyApps/log.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| path | String | required | The path to which application log files should be written |
Restricts a user_apps or user_dirs (autouser) scope to require membership in one or more groups (or, if no arguments are passed, lifts group restrictions from a members_of directive in a parent scope).
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| groups | String | multiple | Users must be a member of at least one of these groups in order to deploy applications; if no groups are provided, then all users are allowed |
Configure Google Analytics tracking code to be inserted in Shiny application pages.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| gaid | String | required | The Google tracking ID, for example, UA-18988-1 |
Defines the amount of time Shiny Server will wait for an R process to start before giving up.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| timeout | Integer | required | The number of seconds to wait for the application to start. |
Top-level, server, location, application
Yes
Defines the amount of time an R process will persist with no connections before being terminated.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| timeout | Integer | required | The number of seconds to keep an empty R process alive before killing it. |
Top-level, server, location, application
Yes
A basic scheduler which will spawn one single-threaded R worker for each application. If no scheduler is specified, this is the default scheduler.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| maxRequests | Integer | optional | The maximum number of requests to assign to this scheduler before it should start returning rejecting incoming traffic using a '503 - Service Unavailable' message. Once this threshold is hit, users attempting to initialize a new session will receive 503 errors. | 100 |
Top-level, server, location, application
Yes
If present, will allow users to override the global defaults for a scheduler by customizing the parameters associated with a scheduler or even the type of scheduler used.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| enabled | Boolean | optional | Whether or not this is enabled. Default is true. | true |
Top-level
Yes
DEPRECATED. This setting is deprecated and no longer enforced in Shiny Server. It will be ignored.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| empty | String | required |
location
Yes
app_init_timeout, app_idle_timeout, simple_scheduler
A directory containing custom templates to be used when generating pages in Shiny Server.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| dir | String | required | The directory containing HTML templates. |
Disable WebSockets on connections to the server. Some networks will not reliably support WebSockets, so this setting can be used to force Shiny Server to fall back to another protocol to communicate with the server. This is equivalent to adding 'websocket' to disabled_protocols
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| val | Boolean | optional | Whether or not WebSockets should be disabled. | true |
Top-level
Yes
Disable some of the SockJS protocols used to establish a connection between your users and your server. Some network configurations cause problems with particular protocols; this option allows you to disable those.
| Parameter | Data type | Type | Description | Default |
|---|---|---|---|---|
| names | String | multiple | The protocol(s) to disable. Available protocols are: 'websocket', 'xdr-streaming', 'xhr-streaming', 'iframe-eventsource', 'iframe-htmlfile', 'xdr-polling', 'xhr-polling', 'iframe-xhr-polling', 'jsonp-polling' |
Top-level
Yes
Shiny Server 0.4 and later include many major changes to the architecture of Shiny Server. There are a few things to be aware of when upgrading from Shiny Server 0.3.x.
First, Shiny Server is now distributed via deb and rpm installers, rather than using npm. Thus, you'll first want to uninstall the old version of Shiny Server which was installed from npm.
$ sudo npm uninstall -g shiny-serverShiny Server no longer requires node.js to be installed on the system either. If you have no other need for node.js, you can uninstall it at this time, as well.
Running the latest Shiny Server installer will replace the scripts at /etc/init/shiny-server.conf or /etc/init.d/shiny-server. If you have made any modifications to these startup scripts that you wish to keep, please save a copy of these files before running the installer.
The default directories for logging and Shiny application hosting have also moved in this release. The default logging directory used to be /var/shiny-server/log, it is now /var/log/shiny-server. The default hosting directory was previously /var/shiny-server/www and is now /srv/shiny-server/. If you have not explicitly overridden these directories in the /etc/shiny-server/shiny-server.conf file, the new location will be created and used in the latest Shiny Server.
Finally, Shiny Server 0.4 and later require the Shiny package to be at least version 0.7.0. You can check the system-wide version of Shiny you have installed using the following command on the command line.
$ sudo su - -c "R -e \"packageVersion('shiny')\""(Running this command using the sudo su - -c preface will allow you to see the system-wide version of Shiny. Individual users could have installed more recent versions of Shiny in their own R libraries.) If the installed version of Shiny predates 0.7.0, you should follow the instructions in Install Shiny to update to the most recent version.
At this point, you can proceed with the Installation instructions associated with your Operating System.
There are problems on some systems with updating from 0.4.x versions to a more recent version. Thus, any user updating from the 0.4.x line should uninstall the package before installing the new one. In all versions 0.5.x and later, updating can simply be done by installing the newer version over the old one without explicitly removing the old package.
The performance footprint of a Shiny application is almost entirely dependent upon the Shiny application code. There are two factors to consider when selecting the hardware platform for Shiny Server.
RAM
The memory requirements of a Shiny application depend heavily on the data loaded when running the application. Often users find that a Shiny R process requires a minimum of 50MB of RAM -- beyond this, the amount of memory consumed by an application is determined by the data loaded or generated by that application. The Scoping Section of the Shiny Tutorial describes in detail how to take advantage of Shiny's scoping rules to share data across multiple Shiny sessions. This enables application developers to load only one copy of data into memory but still share this data with multiple shiny sessions.
CPU
R is fundamentally a single-threaded application. Unless parallel packages and tools are specifically selected when designing a Shiny application, the average R process (and the associated Shiny application) will be run serially on a single processing core. Thus, the typical Shiny application may saturate the processing core to which it's assigned, but will be unable to leverage other cores on the server which may be idle at that time.
Absolutely. Many customers deploy Shiny Server and Shiny Server Professional on the Amazon Web Services (AWS) framework.
Of course. Shiny Server does not require a connection to the Internet in order to work properly, so you are free to deploy it in whatever sort of network configuration you would like. Offline activation is also available for Shiny Server Professional customers.
Shiny Server 0.4.2 introduced a new model for managing applications at a more granular level by supporting nested location directives. Any existing application directives in your configuration file will need to be migrated to this nested location format in order to be supported by any version of Shiny Server after 0.4.2.
application directives were addressed by their full path on disk. Nested locations, on the other hand, are indexed by their relative path within their parent location. For instance, the following exemplifies how you could redirect a particular application in the old model:
location / {
site_dir /srv/shiny-server;
# Define rules to apply to one application, stored at '/srv/shiny-server/app1'
application /srv/shiny-server/app1 {
redirect "http://rstudio.com" 302 true;
}
}In the new "nested locations" model, the equivalent would be:
location / {
site_dir /srv/shiny-server;
# Define rules to apply to one application, stored at '/srv/shiny-server/app1'
location /app1 {
redirect "http://rstudio.com" 302 true;
}
}This structure is much more powerful than simple application settings. The following configuration defines a parent location (depts) with some settings, then overrides those settings for a particular directory (finance) within that location.
server {
...
# Define the '/depts' location
location /depts {
# Host a directory of applications
site_dir /srv/departmentApps;
# Provide a default/global GAID
google_analytics_id "UA-12345-1";
# Define the '/finance' location.
# Corresponds to the URL '/depts/finance', and the filesystem path
# '/srv/departmentApps/finance' as defined by the parent location.
location /finance {
# Provide a custom GAID for only this sub-location
google_analytics_id "UA-54321-9";
location /fall2014/app1 {
redirect "http://rstudio.com" 302 true;
}
}
}
...In this case, all applications stored in the depts/finance/ directory would have a different Google Analytics ID than the rest of the applications on this server. Additionally, the application at depts/finance/fall2014/app1 would be redirected to http://rstudio.com.
Firefox limits the persistent connections that the browser will have open to a single server. For most use cases, this won't be a problem. But a user who opens multiple Shiny Docs with many embedded Shiny components all at once may start hitting this limit.
To resolve this, increase the network.http.max-persistent-connections-per-server setting (we tested by setting it to 50). Once that limit is increased, you should be able to open many complex Shiny Docs simultaneously from Firefox without issue.