Package {tinyshinyserver}

tinyshinyserver: Tiny Shiny Server - Lightweight Multi-App Shiny Proxy

Description

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

Main functions

start_tss

Start the Tiny Shiny Server with a configuration file

Key features

• Host multiple Shiny applications behind a single proxy

• Resident (always-running) and on-demand application modes

• WebSocket support with session affinity

• Real-time management interface and monitoring

• Automatic health checks and application restart

• Cross-platform support (Windows, Linux, macOS)

• Support for R Markdown and Quarto dashboards

Getting started

See example-config for copying and running the included apps and their prerequisites. Use start_tss to launch the server and config-format to configure your own apps.

Package resources

The package includes:

• Example Shiny applications in inst/examples/

• HTML templates and CSS in inst/templates/

• Sample configuration file inst/examples/config.json

Use system.file("examples", package = "tinyshinyserver") to locate the example files after installation.

Author(s)

Maintainer: Lars Bernhardsson cran.sherry228@passinbox.com

Authors:

• Lars Bernhardsson cran.sherry228@passinbox.com

See Also

Useful links:

• https://github.com/lab1702/tinyshinyserver

• Report bugs at https://github.com/lab1702/tinyshinyserver/issues

Configuration File Format

Description

Details about the JSON configuration file format used by start_tss.

Configuration Structure

The configuration file should be a valid JSON file with the following structure:

{
  "apps": [
    {
      "name": "app-name",
      "path": "./path/to/app",
      "resident": true,
      "appstart_timeout": 2
    }
  ],
  "starting_port": 3001,
  "proxy_port": 3838,
  "proxy_host": "127.0.0.1",
  "management_port": 3839,
  "restart_delay": 5,
  "health_check_interval": 10,
  "log_dir": "./logs"
}

Relative application paths and log_dir are resolved from the R working directory (getwd()), not the configuration file's directory. JSON does not allow comments.

Required Fields

apps

Array of Shiny applications to host. Each app must have name and path.

starting_port

Starting port number for automatic app port assignment.

log_dir

Directory where server and application logs will be written.

Optional Fields

proxy_port

Port for the main proxy server (default: 3838).

proxy_host

Host interface to bind to (default: "127.0.0.1").

management_port

Port for the management interface (default: 3839).

restart_delay

Non-negative finite seconds to wait before restarting failed apps (default: 5).

health_check_interval

Positive finite seconds between health checks (default: 10).

Application Configuration

Each application in the apps array can have:

name

Unique identifier used in URLs and logs: 1–50 ASCII letters, digits, underscores, or hyphens. Required.

path

Path to the app directory, absolute or relative to the R working directory. Required.

resident

Boolean. If true, app runs continuously. If false (default), app starts on-demand.

appstart_timeout

Positive, finite number of seconds from app startup to wait for readiness before returning HTTP 503 (default: 2). Fractional seconds are supported.

Host Configuration

The proxy_host field controls the proxy's listening interface. The management server and backend apps always bind to 127.0.0.1. Supported proxy hosts are:

• "127.0.0.1" or "localhost": Localhost only (most secure)

• "0.0.0.0": All network interfaces (allows external access)

• "::1": IPv6 localhost

• "::": All IPv6 interfaces

Port Assignment

Apps are automatically assigned ports starting from starting_port, skipping reserved ports (proxy_port and management_port) and ports already in use. For example, with starting_port: 3001, apps might get ports 3001, 3002, 3003, etc., but will skip 3838 and 3839 if those are the proxy and management ports.

See Also

start_tss for starting the server with a configuration file.

Use system.file("examples", "config.json", package = "tinyshinyserver") to see a complete example configuration file.

Examples

if (interactive()) {
  (function() {
    example_dir <- tempfile("tss-example-")
    dir.create(example_dir)
    old_dir <- setwd(example_dir)
    on.exit({
      setwd(old_dir)
      unlink(example_dir, recursive = TRUE)
    }, add = TRUE)
    examples_path <- system.file("examples", package = "tinyshinyserver")
    file.copy(examples_path, ".", recursive = TRUE)
    config_content <- '{
      "apps": [
        {"name": "sales", "path": "./examples/sales", "resident": true},
        {"name": "inventory", "path": "./examples/inventory", "resident": false}
      ],
      "starting_port": 3001,
      "proxy_port": 3838,
      "management_port": 3839,
      "log_dir": "./logs"
    }'
    writeLines(config_content, "my-config.json")
    start_tss(config = "my-config.json")
  })()
}

Example Configuration File

Description

This provides the path to the example config.json file that demonstrates the proper configuration format for start_tss. The file includes sample applications and typical server settings.

Format

A JSON file with the standard configuration structure. See config-format for details about the configuration format.

Details

Path to the example configuration file included with the package.

The example configuration includes:

• Four sample Shiny applications (sales, inventory, reports, dashboard)

• Mix of resident and on-demand application modes

• Standard port configuration (proxy: 3838, management: 3839)

• Automatic port assignment starting from 3001

• Logging configuration

Run the copied configuration from the directory containing examples/. The reports and dashboard examples require DT, plotly, dplyr, and flexdashboard; document apps also need Pandoc or the Quarto CLI.

See Also

• start_tss for starting the server

• config-format for configuration file format details

Examples

if (interactive()) {
  (function() {
    example_dir <- tempfile("tss-example-")
    dir.create(example_dir)
    old_dir <- setwd(example_dir)
    on.exit({
      setwd(old_dir)
      unlink(example_dir, recursive = TRUE)
    }, add = TRUE)
    examples_path <- system.file("examples", package = "tinyshinyserver")
    file.copy(examples_path, ".", recursive = TRUE)
    cat(readLines("examples/config.json"), sep = "\n")
    start_tss(config = "examples/config.json")
  })()
}

Start Tiny Shiny Server

Description

Launch the Tiny Shiny Server using a configuration JSON file. This starts a multi-application Shiny server with automatic health monitoring, session management, and WebSocket support.

Usage

start_tss(config = "config.json")

Arguments

Details

See config-format for required fields, defaults, app lifecycle settings, and port assignment. Relative app paths and the log directory are resolved from the R working directory, not the configuration file's directory.

Access points with the default ports:

• Main landing page: ⁠http://localhost:3838⁠

• Management interface: ⁠http://localhost:3839⁠

• Individual apps: ⁠http://localhost:3838/proxy/{app_name}/⁠

Value

Invisibly returns the TinyShinyServer instance after the server stops. This function blocks until interrupted (Ctrl-C) or shut down via the management interface.

Examples

if (interactive()) {
  (function() {
    example_dir <- tempfile("tss-example-")
    dir.create(example_dir)
    old_dir <- setwd(example_dir)
    on.exit({
      setwd(old_dir)
      unlink(example_dir, recursive = TRUE)
    }, add = TRUE)
    examples_path <- system.file("examples", package = "tinyshinyserver")
    file.copy(examples_path, ".", recursive = TRUE)
    start_tss(config = "examples/config.json")
  })()
}