tinyshinyserver

A lightweight, WebSocket-enabled proxy server for hosting multiple Shiny applications with automatic health monitoring, session management, and resource cleanup.

Use it to host Shiny apps, interactive R Markdown documents, and Quarto dashboards behind one proxy. Apps can stay running or start on demand. For deployments beyond localhost, see Network access and authentication.

Installation

From CRAN

# Install from CRAN
install.packages("tinyshinyserver")

From GitHub

# Install from GitHub
remotes::install_github("lab1702/tinyshinyserver")

From source

# Clone and install locally
git clone https://github.com/lab1702/tinyshinyserver.git
cd tinyshinyserver
Rscript -e "devtools::install('.')"

Prerequisites

• R (≥ 4.0)
• Pandoc (for R Markdown apps)
• Quarto CLI (optional, for Quarto dashboards)

Required R dependencies are installed with the package. The bundled reports and Quarto dashboard also need the example packages installed below; Pandoc and the Quarto CLI must be available separately.

Quick start

Run these commands in R from the directory where you want to keep the examples:

install.packages(c("DT", "plotly", "dplyr", "flexdashboard"))
library(tinyshinyserver)

examples_path <- system.file("examples", package = "tinyshinyserver")
file.copy(examples_path, ".", recursive = TRUE)
start_tss(config = "examples/config.json")

The example configuration includes a Quarto app that starts immediately. Install the Quarto CLI before using the full configuration, or use the sales-only configuration below to try a standard Shiny app.

With the default ports, open:

• Landing page (http://localhost:3838): app links and status
• Management dashboard (http://localhost:3839): monitoring, restarts, and shutdown
• Sales app (http://localhost:3838/proxy/sales/): an individual app

start_tss() occupies the R console until shutdown. Click Shutdown Server in the management dashboard or press Ctrl-C in R to close connections and stop the app processes. For scripted shutdown, see Management API.

Features

• Host multiple apps behind one HTTP and WebSocket proxy, with a separate R process for each app.
• Choose resident or on-demand apps to balance startup delay and resource use.
• Monitor app status and WebSocket connections, restart individual apps, and shut down from a web dashboard.
• Automatically restart failed resident processes and clean up stale connections.
• Serve standard Shiny apps, interactive R Markdown documents, and Quarto dashboards.
• Capture server logs and each app’s output and errors.

Configuration

The server reads a JSON configuration file. After copying the examples, save this sales-only configuration as config.json in your working directory and run start_tss():

{
  "apps": [
    {
      "name": "sales",
      "path": "./examples/sales",
      "resident": true
    }
  ],
  "starting_port": 3001,
  "proxy_port": 3838,
  "proxy_host": "127.0.0.1",
  "management_port": 3839,
  "log_dir": "./logs"
}

apps, starting_port, and log_dir are required. Other server settings have defaults. Relative app paths and log_dir are resolved from the R working directory (getwd()), not from the configuration file’s directory. Absolute paths are also supported.

JSON does not allow comments. See help("config-format") for the complete reference.

Included examples

The package includes four example applications:

The bundled example configuration keeps sales and dashboard resident; inventory and reports start on demand. In the source repository, the apps are under inst/examples/; the quick start copies them to examples/.

App ports and lifecycle

Apps receive ports in configuration order, starting from starting_port. Allocation skips the proxy port, management port, and ports already in use. With the example settings and no conflicts, the four apps receive ports 3001–3004. Users access apps through /proxy/{app_name}/ on the proxy port.

On-demand apps stop when their last WebSocket connection closes, provided no HTTP requests remain. If requests are in flight, shutdown waits for them to finish and allows 30 seconds for a new page to establish its WebSocket session. Visits that never open a WebSocket session allow 30 seconds without HTTP activity before shutdown. Failed on-demand apps start again on the next request.

appstart_timeout controls how long a request waits for startup readiness (default: 2 seconds, measured from app startup). If the app is still starting, the proxy returns HTTP 503. Increase this value for slow-starting apps; fractional seconds are supported.

Configuration options

Network access and authentication

proxy_host controls the proxy’s listening interface. The management server and backend apps always bind to 127.0.0.1.

The server is intended for development and internal use. It does not provide built-in authentication or TLS. For external access, put an authenticated HTTPS reverse proxy in front of it and restrict direct access with firewall rules.

Caddy example

Keep proxy_host set to "127.0.0.1" when running Caddy on the same machine. Replace the domains, usernames, and hash placeholders below. Generate each password hash with caddy hash-password; Caddy’s basic_auth directive requires hashed passwords.

myapp.example.com {
    reverse_proxy 127.0.0.1:3838
    basic_auth {
        username REPLACE_WITH_PASSWORD_HASH
    }
}

manage.myapp.example.com {
    reverse_proxy 127.0.0.1:3839
    basic_auth {
        admin REPLACE_WITH_ADMIN_PASSWORD_HASH
    }
}

Include the management site only if remote administration is needed. Keep cross-origin CORS access disabled on its reverse proxy; see Management API for the required request header.

Monitoring and management

Both web pages refresh status every 5 seconds and follow your system’s light or dark theme.

App status is running, dormant (an unused on-demand app), stopped, or crashed. Running and dormant apps can be opened from the landing page; opening a dormant app starts it. Stopped or crashed tiles are disabled, and all tiles are disabled when the server is unreachable.

The management dashboard shows active WebSocket connections, including client IP addresses, user agents, connection times, and last activity. Restart controls are available for running, stopped, and crashed apps. Dormant apps start on access. Restarting an app disconnects its users.

Proxy endpoints

These read-only endpoints are served on the proxy port:

Management API

These endpoints are served on the management port (default: 3839). POST requests require the X-TinyShinyServer-Request: management header to prevent cross-origin browser requests. The dashboard sends this header automatically. Cross-origin CORS access must remain disabled on any reverse proxy:

Example usage:

# Get system status
curl http://localhost:3839/api/status

# Restart the sales app
curl -X POST -H "X-TinyShinyServer-Request: management" http://localhost:3839/api/apps/sales/restart

# Shutdown server
curl -X POST -H "X-TinyShinyServer-Request: management" http://localhost:3839/api/shutdown

Application structure

Point each app’s path at a directory containing one of these entry points:

Detection prefers standard Shiny files, then R Markdown, then Quarto. For document apps, the first matching file returned by list.files() is used; keep one entry document per directory to make the choice explicit.

To add an app, create its directory, add an entry with name and path to the configuration, and restart the server.

For local development, run a copied example directly from R:

shiny::runApp("examples/sales", port = 3001)
rmarkdown::run("examples/reports/report.Rmd",
               shiny_args = list(port = 3003, host = "127.0.0.1"))
quarto::quarto_serve("examples/dashboard/dashboard.qmd",
                     port = 3004, host = "127.0.0.1")

Run one command at a time, with tinyshinyserver stopped or a different port selected.

Memory management

The server includes automatic memory management features:

• Connection Cleanup: Removes stale connections after 30 minutes of inactivity
• Queue Limits: Limits pending message queues to 100 messages per connection
• Process Cleanup: Removes dead process objects from memory
• File Handle Management: Ensures proper cleanup of log file handles

Cleanup runs automatically every 5 minutes and logs activity for monitoring.

Logging

Log files

With "log_dir": "./logs", the server writes:

• logs/server.log - Main server logs
• logs/{app_name}_output.log - Per-app stdout logs
• logs/{app_name}_error.log - Per-app stderr logs

Log levels

• INFO - Normal operations
• WARN - Warning conditions (e.g., queue limits reached)
• ERROR - Error conditions requiring attention

Architecture

The R process running start_tss() serves the proxy and management interfaces. Each active app runs in a separate background R process on its assigned localhost port. The proxy forwards HTTP requests and WebSocket messages to that app.

Periodic checks detect exited app processes and restart resident apps. These checks do not assess whether a running app is responsive or producing correct results.

Source code lives in R/, generated help pages in man/, example apps in inst/examples/, and shared styles in inst/templates/.

Troubleshooting

Common issues

Inspecting logs

In R, list the logs under your configured log_dir:

list.files("logs", pattern = "\\.log$")

To follow the main log from a terminal:

# Linux/macOS
tail -f logs/server.log

# PowerShell
Get-Content logs/server.log -Wait

Contributing

To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Test thoroughly: devtools::check()
5. Submit a pull request

Development setup

Clone the repository in a terminal:

git clone https://github.com/lab1702/tinyshinyserver.git
cd tinyshinyserver

Then run in R from the repository root:

devtools::install_deps(dependencies = TRUE)
devtools::load_all()
devtools::check()

Edit help-page documentation in the roxygen comments in R/, then regenerate man/ with devtools::document().

Help and support

• R help: ?tinyshinyserver, ?start_tss, help("config-format"), help("example-config")
• Bug reports: GitHub Issues