Configuration¶
ShinyHub reads server configuration from YAML and allows environment variables
to override individual values. The complete annotated reference is
shinyhub.yaml.example.
Configuration file resolution¶
The server checks, in order:
shinyhub serve --config /path/to/shinyhub.yamlSHINYHUB_CONFIG./shinyhub.yaml
init, validate-config, backup, and restore use the same resolution order.
Validate before restarting¶
Run the candidate binary against the candidate configuration before stopping the running service:
The command uses the same configuration loader, defaults, and environment
overrides as serve. Run it with the service's environment (including secrets),
working directory, and file permissions so it checks the effective deployment
configuration. It exits with status 0 on success and 1 on a configuration
error, reporting the validation error without dumping the configuration.
--output json is available for automation.
A file explicitly selected with --config or SHINYHUB_CONFIG must exist.
Without an explicit path, a missing ./shinyhub.yaml permits environment-only
configuration. An existing default file is still loaded and validated.
A key the loader does not know is an error at every depth, not only at the top
level. The error names the full path (server.drian_timeout) and, where it
can, the key you probably meant: the closest spelling at that level, or the
section that does accept that key when it was written under the wrong one
(defaults.timezone points at scheduler.timezone). Fields that take
arbitrary keys, such as tracing.resource_attributes, accept anything.
Validation does not start listeners, open or migrate a database, launch apps,
or modify server state. It does not verify DNS, certificate coverage, SSO,
database connectivity, or runtime readiness. Continue to check /readyz after
starting the service.
If startup validation fails, ShinyHub exits before opening its HTTP listener.
A refused connection to /readyz therefore cannot show the configuration error;
read the process's stderr or service log. For a systemd service named
shinyhub, use journalctl -u shinyhub -n 100 --no-pager. Run preflight before
the deployment's stop/restart step; an ExecStartPre check alone is too late to
preserve the running instance during a restart.
Minimal server¶
database:
driver: sqlite
dsn: /var/lib/shinyhub/shinyhub.db
server:
host: 127.0.0.1
port: 8080
base_url: https://hub.example.com
auth:
secret: replace-with-at-least-32-random-characters
storage:
apps_dir: /var/lib/shinyhub/apps
app_data_dir: /var/lib/shinyhub/app-data
Generate auth.secret once and preserve it across restarts:
The secret signs sessions and encrypts application secrets at rest. Follow the secret rotation procedure instead of replacing it directly on a running installation.
Schema migrations on startup¶
The server applies any pending migrations when it starts. Before it changes the schema it copies the SQLite database aside, so an upgrade that turns out bad can be rolled back by restoring the old binary and that file:
INFO pre-migration snapshot written
path=/var/lib/shinyhub/shinyhub.db.pre-migration-v58-20260819T091223Z.sqlite
pending_migrations=1 retention=5
The snapshot is written only when migrations are actually pending, so ordinary
restarts and same-version reloads write nothing. It is a complete, self-contained
database (no -wal/-shm sidecars) taken with VACUUM INTO, safe to run while
the server is live.
After a new snapshot is written, older ones beyond
database.pre_migration_snapshot_retention are pruned automatically, so an
instance upgraded regularly does not accumulate one full-size copy of the
database per upgrade forever. The newest snapshot is always kept regardless of
the retention count: it is the only route back to the build that ran before
the last upgrade, and a snapshot cannot be regenerated afterwards since it is
a copy of a schema version the current binary no longer writes.
database:
pre_migration_snapshot: false # SHINYHUB_DB_PRE_MIGRATION_SNAPSHOT
pre_migration_snapshot_retention: 5 # SHINYHUB_DB_PRE_MIGRATION_SNAPSHOT_RETENTION
Turn it off when an external backup already covers the upgrade, or when the database is too large to copy inside the service start timeout. While it is on, a snapshot that cannot be written aborts startup: migrating a database the operator cannot get back is worse than not starting.
Postgres deployments log a warning instead, because VACUUM INTO is SQLite-only.
Take a pg_dump before an upgrade that carries migrations.
Downgrades exit 7¶
A database migrated by a newer build is never served by an older one: the schema
carries columns this code cannot read. The server refuses to start and exits
with code 7 (schema_incompatible), naming the two versions and what to do:
database schema is newer than this binary: database is at schema version 59,
this binary supports up to 58. Downgrade is not supported and this will not
succeed on retry.
The condition is permanent, so the packaged systemd unit sets
RestartPreventExitStatus=7. Without it the unit restart-loops and reports
activating (auto-restart), which most monitoring reads as healthy while the
service is in fact down.
Getting back to the older build¶
The fastest resolution is to start the newer build again. To stay on the older one, restore state it can read. There are two artifacts, and they are restored differently:
A pre-migration snapshot is a bare database file, so it is moved back into place rather than fed to a command:
systemctl stop shinyhub
mv /var/lib/shinyhub/shinyhub.db.pre-migration-v58-20260819T091223Z.sqlite \
/var/lib/shinyhub/shinyhub.db
rm -f /var/lib/shinyhub/shinyhub.db-wal /var/lib/shinyhub/shinyhub.db-shm
systemctl start shinyhub
Delete the -wal and -shm sidecars as shown. They belong to the migrated
database, and SQLite replays them over whatever file it finds at that path: leave
them and the rows you just rolled back come straight back, with no error and no
warning. The snapshot itself needs no sidecars, being a self-contained
VACUUM INTO copy.
A backup archive from shinyhub backup is a .tar.gz containing the
database plus the apps and app-data trees, and is restored with the command:
systemctl stop shinyhub
shinyhub restore /var/backups/shinyhub-20260819.tar.gz
systemctl start shinyhub
The two are not interchangeable: handing a snapshot to shinyhub restore is
rejected, with the move-it-into-place instructions above. Note the difference in
scope, which matters when choosing between them - a snapshot rolls back the
database alone, so any deploy that landed after it was taken stays on disk while
the database no longer knows about it. An archive rolls back all three together.
The systemctl stop is not advisory. Restoring into a live server renames the
database out from under an open connection. shinyhub restore refuses to run
while it can see a server: a running server publishes <database>-running.json
beside its database file, so the refusal works from the database path alone,
which is the one setting a restore cannot get wrong. server.pid_file naming a
live process and anything listening on server.host/server.port are also
treated as a running server. A marker left by a crash names a dead process and
is ignored. --force skips the check, for a server you have confirmed stopped
by other means.
Dedicated application origin¶
Production deployments should serve application traffic from an origin that is different from the dashboard and API:
Route both HTTPS hostnames to the same ShinyHub listener. The application origin
exposes app proxy traffic and health checks only; it does not expose the
dashboard, static control-plane assets, or /api routes. This prevents
application JavaScript from sharing an origin with control-plane cookies.
Without app_origin, every deployed app runs same-origin with the dashboard,
and ShinyHub trusts every deployed app with dashboard users' sessions. App
JavaScript shares the dashboard's origin, so a malicious or compromised app can
attempt to read same-origin state, ride an admin's session for same-origin
requests, or otherwise act with the authority of whoever is viewing it. The
CSRF double-submit-cookie check and the Referer-based defense in
internal/auth/csrf.go reduce this risk but do not eliminate it - they are a
mitigation for the same-origin case, not a substitute for isolation. Set
app_origin whenever any deployed app's code is not fully trusted; a server
started without it logs a startup warning for exactly this reason.
The isolated origin also unlocks optional administrator support sessions. See Support sessions for the opt-in setting and security model.
Application status overlay¶
When an application's WebSocket drops mid-session, Shiny shows a grey "disconnected" box. It cannot say more than that: the application process is the one party that does not know whether it was hibernated, redeployed, or killed. ShinyHub does know, so its proxy appends a small script to application HTML page loads that explains the disconnect and offers a reload.
On by default. What it does, and what it deliberately does not do:
- It appends one
<script>before</body>on top-level HTML navigations only. Sub-resources, XHR, JSON, WebSocket upgrades, redirects, and error responses are never touched. - It runs after the application's own bootstrap and replaces no global. It
watches for the
#shiny-disconnected-overlayelement that R and Python Shiny both add, and does nothing in an application that never adds one. - On a disconnect it polls the application's readiness endpoint and reports whether the app is back, gone, or still down. Polling is read only: it never reaches the application and never wakes it.
- If the application sets a
Content-Security-Policy, ShinyHub adds the overlay'ssha256script hash to it and nothing else. A policy that forbids scripts outright ('none') is honoured by skipping the injection, never by relaxing the policy. - Page loads are fetched from the backend uncompressed so the script can be spliced in. The backend hop still negotiates gzip; only the in-process view is plain, and the finished page is compressed on its way to the visitor (see Response compression).
Set it to false for byte-for-byte untouched application responses. No response
body is rewritten while it is off.
Anonymous app availability monitoring¶
Enable a non-waking availability check for explicitly selected apps:
The default is an empty list. SHINYHUB_SERVER_PUBLIC_APP_AVAILABILITY=sales,reports
overrides the list; set it to [] to clear the central allowlist. Only exact, valid
app slugs are accepted; wildcards are rejected. Keep configuration consistent
across instances. This setting exposes existence and coarse operational state
for listed apps, including private apps; it grants no access to app content.
The allowlist follows the slug: if an app is deleted and its slug reused, the
replacement inherits this exposure. Remove retired entries when appropriate.
Restart the server or perform a zero-downtime reload
to apply server monitoring settings; the handler captures them at startup.
App owners can instead declare exposure in their own deployment configuration, when the operator permits it:
In an app's shinyhub.toml:
[app]
availability = "public" # inherit | off | public; new ordinary apps inherit an off server default
Or in a fleet manifest:
fleet_id = "analytics"
[[app]]
slug = "sales"
source = "./sales"
[app.config]
availability = "public"
The effective exposure is the union of the central allowlist and explicit or
inherited public exposure permitted by the server. availability = "off" revokes the app opt-in, but
cannot override the operator's central allowlist. Omitting the key preserves
the stored value. Fleet config takes precedence over a source bundle and is
reconciled even when its digest is unchanged. App settings take effect when
committed, with no ShinyHub restart or app activation required; authorized
owners and users with app management rights can also use
PATCH /api/apps/<slug> with {"availability":"off"} or
{"availability":"public"}, or {"availability":"inherit"}. Changing only fleet monitoring config uses PATCH
without restarting workers or changing the bundle digest. New fleet apps receive
the effective fleet or source declaration at creation,
so a failed first boot is monitored too. A conflicting declaration in the
source manifest is overridden in the uploaded manifest and follows the usual
deployment path. Out-of-band exposure drift is corrected through PATCH. Rollback
uses the stored exposure setting and does not restore an opt-in from an older
bundle.
The server rejects new public declarations when opt-in is denied; off is
always allowed. Unchanged stored public declarations remain valid during
redeployment while their exposure is suppressed. Setting the server policy back
to deny suppresses stored app opt-ins without erasing them, so changing it to allow later restores
them. The central allowlist continues to work under either policy. To disable
all exposure, clear the central list and set opt-in to deny.
SHINYHUB_SERVER_APP_AVAILABILITY_OPT_IN overrides this policy.
An opt-in is attached to the app record: deletion and slug reuse do not transfer
it. Central allowlist entries still follow the slug. App visibility (private,
shared, public) is independent of monitoring exposure. An app opt-in reveals
its existence and coarse state even when its content is private.
Like other declared app metadata, a stop-first deploy commits exposure during manifest reconciliation; it can remain exposed if the subsequent boot fails, which lets monitors detect that failure. A parallel generation handoff stages it with the candidate's settings and publishes it at successful cutover. A policy or manifest validation rejection does not change exposure.
Server-wide default exposure¶
To include future ordinary apps automatically, enable app-derived exposure and set a public default. Fleet discovery remains a separate switch:
server:
app_availability_opt_in: allow
app_availability_default: public # "off" | public; default: "off"
public_fleet_availability: true
SHINYHUB_SERVER_APP_AVAILABILITY_DEFAULT overrides the default. This is an
operator decision to disclose app slugs and coarse state, including private
apps whose owners make no declaration. It changes no content access rules.
Like the other monitoring settings, it takes effect after a restart or
zero-downtime reload; keep it consistent across HA instances.
An app's stored availability intent is one of:
inherit: followserver.app_availability_default, subject toallow.off: opt out of the default, even when the default is public.public: explicitly request public monitoring, subject toallow.
New ordinary apps without a declaration store inherit at creation, so they
are covered even before upload or a failed first boot. Development and ephemeral
apps created by deploy --watch --create or --ephemeral instead start at off
unless explicitly configured; their frequent creation and expiry would otherwise
cause inventory churn. A failed request before an app record exists cannot be
reported by this inventory.
The operator's central allowlist overrides all three intents and continues to
work under deny. Setting app_availability_opt_in: deny suppresses both explicit
public intent and public inheritance without changing stored intent. A public
default combined with deny is valid but logs a warning. Clear the central list
as well to disable all anonymous exposure.
Omission on PATCH or redeployment preserves stored intent. To resume following
the server after an explicit opt-out, declare availability = "inherit", use
PATCH /api/apps/<slug> with {"availability":"inherit"}, choose Follow server
default in the app's general settings, or run:
inherit and off are accepted under deny; new explicit public remains
rejected. Changing server defaults never rewrites app intent. Switching the
default back to off withdraws only inherited exposure, leaving explicit public
settings and central allowlists intact.
Upgrade existing apps deliberately. Prior versions stored both an omitted
setting and an explicit opt-out as off. Migration preserves every existing
off and public value; it never guesses owner intent from old bundles or audit
history. Existing apps therefore do not automatically inherit. Operators can
review a paginated, authenticated GET /api/apps?availability=off inventory and
use the normal audited PATCH or apps set above for each app approved to inherit.
Review and convert while the server default is still off, then enable public.
An explicit off in a source or fleet manifest reasserts that opt-out on its next
deployment. For fleet-managed apps, change the fleet manifest to inherit as well:
fleet apply reconciles declared intent, so UI changes and migration PATCHes that
conflict with that manifest are drift and will be reverted. Central allowlisting
is an alternative but prevents owner opt-out.
For callers with app management rights, the authenticated app list and details add availability_exposure with intent,
exposed, source (app, default, allowlist, or none) and
policy_suppressed, plus app_allowed to explain whether new public declarations
are permitted. General settings and fleet plan show effective exposure
and its source, including allowlist overrides and policy suppression. An unscoped
operator may filter the apps list by availability=inherit|off|public, with the
usual pagination. The inherit filter previews the apps affected by a server
default change; already allowlisted apps are identifiable from their source.
Anonymous responses do not include this policy metadata.
Servers advertise availability_inherit; a new fleet CLI refuses explicit
inherit against older servers. Plain deploy to an older server rejects an
inherit manifest through its normal manifest validation; upgrade the server
before using that declaration. fleet init preserves all three stored intents,
including inherit, so a conflicting source declaration cannot change them on
recreation. Upgrade all control planes before enabling public inheritance:
predecessor servers suppress inherited exposure and predecessor server creations
still default to off. Old clients that explicitly send off continue opting
out. Keep the fleet snapshot's 10,000-app limit and one-second deadline in mind;
exceeding either fails the entire snapshot rather than silently truncating it.
Deleted apps, revoked exposure and expired ephemeral apps disappear, so monitors
still need remembered or expected membership.
Probe GET /app/sales/.shinyhub/availability on the hostname used for apps:
A hibernated app eligible to activate returns:
| Condition | HTTP | Response fields |
|---|---|---|
| Published release has a fresh-session route | 200 | available:true, lifecycle status, basis:"serving_route" |
| Degraded app with surviving routes | 200 | available:true, status:"degraded", basis:"serving_route" |
| Hibernated app with a successful serving release and no activation blocker | 200 | available:true, status:"hibernated", basis:"activation_eligible" |
| Published demand-driven pool eligible to allocate workers, including during a replacement deploy/start | 200 | available:true, lifecycle status, basis:"activation_eligible"; no worker is allocated |
| Deploying/starting/waking app with a previous release still serving | 200 | available:true, lifecycle status, basis:"serving_route" |
| Compatibility failure, including an unrepaired producer barrier | 503 | available:false, status:"quarantined", reason:"compatibility_blocked" |
| Active data publisher prevents activation, with no existing serving route | 503 | available:false, lifecycle status, reason:"activation_blocked" |
| Confirmed explicit operator stop | 503 | available:false, status:"stopped", reason:"stopped_by_operator" |
| Stopped without recorded operator intent, deleting, failed or crashed app | 503 | available:false, lifecycle status |
| No successful serving release | 503 | available:false, lifecycle status, reason:"no_serving_release" |
| Starting or missing fresh-session capacity | 503 | available:false, lifecycle status, reason:"no_serving_capacity" |
| Hibernating/waking with a successful release and no activation blocker | 200 | available:true, lifecycle status, basis:"activation_eligible" |
| Server starting, draining or not yet synchronized | 503 | available:false, status:"unknown", reason:"platform_unavailable" |
| Database lookup failed, or unrecognized lifecycle state | 503 | available:false, status:"unknown", reason:"state_unavailable" |
| Unlisted, not opted in, policy-suppressed, or confirmed unknown slug | 404 | No app state disclosed |
| Monitoring lookup budget exhausted | 429 | available:false, status:"unknown", reason:"monitor_busy"; retry after one second |
available:true means ShinyHub knows a serving route or an eligible activation
path. Every 200 response names that evidence in basis: serving_route or
activation_eligible. Neither value claims that a synthetic request succeeded.
Responses with available:false omit basis; an optional fixed reason
explains the failure. status always describes lifecycle state, rather than
inferring that a demand-driven app is idle from its worker policy.
stopped_by_operator requires a recorded, confirmed stop operation; stopped
alone does not prove intent. A failed first deployment or restart may also
leave an app stopped. An accepted activation attempt clears the intent before
boot, including when boot fails. Preparation-only deploys that keep an app
stopped preserve it. Existing stopped apps are not backfilled with guessed
intent on upgrade; explicitly stopping them establishes it. Compatibility
quarantine still takes precedence, even for deliberately stopped apps.
Whether to suppress alerts for an intentional stop is the monitor's policy. In HA,
finish upgrading all control-plane instances before writing app opt-ins or
relying on the new stop reason: older instances cannot apply these settings or
maintain stop intent. App resource revisions also change with this upgrade;
re-plan saved fleet plans after the upgrade, and expect revision precondition
failures while requests can reach mixed versions. Configure the same
monitoring policy on every instance behind a load balancer before enabling
fleet discovery. Binary downgrades still require restoring a compatible
pre-migration snapshot or backup; see downgrades.
Compatibility failures take precedence over stale routes and lifecycle status. An active, healthy data publisher blocks new activations but does not invalidate an existing consumer route. A failed deployment attempt does not itself make a still-serving previous release unavailable. Retiring generations and draining replicas do not count as capacity for new sessions.
HEAD returns the same status and headers without a body. Other methods return
405 for enabled, syntactically valid monitoring paths. Responses include
Cache-Control: no-store, including
404s and 429s. At most two monitoring database lookups run concurrently per
server process, shared across all slugs and the fleet endpoint below. Excess probes receive 429 immediately
with Retry-After: 1; they do not queue or query the database. A 429 means the
monitoring service is busy and provides no evidence about app health. Monitors
should retry with backoff and jitter rather than page on a single busy response.
Enabling app opt-in (allow) also lets syntactically valid unknown-slug probes
consume this shared lookup budget; the central allowlist alone rejects unlisted
slugs before a lookup.
The budget is released before writing a response, so a slow client cannot hold
a database slot. Each lookup has a one-second context deadline; an uncertain lookup never
becomes an unknown-app 404. Probes do not contact apps, start workers, request
a wake, set affinity cookies, or record app activity, so polling does not extend
the hibernation window. The existing authenticated .shinyhub/ready endpoint
and browser recovery behavior are unchanged.
This checks the external path to a ShinyHub monitoring handler and reports
ShinyHub's current knowledge of the app. It does not exercise app HTTP or
WebSocket behavior, authentication, or dependencies. activation_eligible
means there is no known activation blocker; it does not prove startup will
succeed, validate bundle files on disk, reserve resources, or promise available
capacity under load. This is not an overload or memory-pressure probe. Lifecycle
state, route observations and later user requests may race, including briefly
disagreeing during a generation switch. Use a separate authenticated synthetic
check when those stronger guarantees are required, accepting that it may wake
the app.
If an upstream proxy enforces authentication, explicitly exempt only the exact
monitoring paths for the configured slugs from that proxy's authentication
check and forward them to ShinyHub. Avoid exempting the entire /app/ prefix
or .shinyhub/ namespace. ShinyHub's allowlist cannot override a rejection
issued upstream. Probe the public app hostname when server.app_origin is set.
Use /healthz for platform liveness and /readyz for platform readiness.
Fleet availability and discovery¶
Separately enable anonymous discovery of the complete exposed inventory:
SHINYHUB_SERVER_PUBLIC_FLEET_AVAILABILITY overrides the discovery switch.
The switch enables GET /.shinyhub/availability on both the control and app
origins, including an isolated server.app_origin. Use the app hostname to
check the externally routed monitoring path. Disabled discovery returns 404
with Cache-Control: no-store and performs no monitoring database lookup.
Existing central allowlists do not implicitly enable discovery.
{
"generated_at": "2026-11-10T13:05:44Z",
"apps": [
{"slug":"reports","available":true,"status":"hibernated","basis":"activation_eligible"},
{"slug":"sales","available":false,"status":"stopped","reason":"stopped_by_operator"}
]
}
Only apps exposed through the effective policy above are listed, once each, in ascending slug order. Unknown central-list entries are omitted. No names, owners, diagnostics or app content are returned. Enabling this endpoint makes those slugs enumerable, including private apps; per-app probes previously required callers to supply a slug. Review that disclosure before enabling it.
Each entry uses the per-app response contract with an added slug. HTTP 200
means a complete inventory was obtained, even if every app is unavailable.
A healthy empty inventory returns "apps":[]. HTTP 503 with the existing
platform_unavailable reason means the platform is starting, unsynchronized
or draining; state_unavailable means the snapshot could not be obtained or
completed. Failure responses omit apps, and must never be interpreted as an
empty healthy fleet. HEAD has the same status and headers without a body;
other methods return 405. All responses include Cache-Control: no-store.
The fleet lookup uses one database statement with a one-second deadline and
shares the two-slot monitoring budget with per-app lookups. It evaluates at
most 10,000 app entries; a larger exposed fleet returns 503 with
state_unavailable, rather than a truncated successful inventory. This is a hard safety cap, not
a throughput guarantee; database load and compatibility metadata can cause a
smaller fleet to exceed the deadline. The budget
is released before writing to the client. A busy monitor still returns 429
with monitor_busy and Retry-After: 1; use bounded retries with backoff and
jitter. One request reduces polling overhead but does not remove resource
limits. The endpoint never contacts apps, wakes workers or records activity.
Database membership and lifecycle state come from one snapshot; routing state
is observed separately and can change during evaluation. generated_at is
the UTC response generation time, not a guarantee of an atomic routing snapshot
or successful synthetic app request.
A monitor should alert separately on missing/invalid responses and on app
unavailability. Remember previous membership or define expected apps: deleted
apps and revoked opt-ins disappear from future inventories. A successful
empty or smaller list alone does not prove all expected apps remain covered.
Suppress stopped_by_operator only when that matches your alerting policy.
For fleet monitoring behind an authenticating proxy, exempt only the exact
/.shinyhub/availability path; this is one exemption regardless of app count.
Do not exempt the .shinyhub/ namespace or /app/ prefix.
Application switcher¶
An open application fills the browser tab, and nothing in it leads anywhere else: a visitor who reaches one application has no way to get to another, or back to the dashboard, short of editing the URL. ShinyHub injects a switcher into application pages that lists the applications this visitor can open, grouped by project.
On by default. What it does, and what it deliberately does not do:
- It appends one
<script>before</body>, on the same top-level HTML navigations the status overlay uses and under the same rules: sub-resources, XHR, JSON, WebSocket upgrades, redirects, and error responses are never touched. When both are enabled they share a single pass over the response. - It renders inside a closed shadow root, so the application's own CSS and the switcher's cannot reach each other.
- It lists only applications the caller is already authorized to see, resolved per request against the same rules as the dashboard. An anonymous visitor sees the public ones. It names no application the caller could not have listed for themselves.
- A visitor can dismiss it for the tab; it comes back on reload.
- It is also added to the pages ShinyHub serves in the application's place - starting, deploying, at capacity, stopped, crashed, awaiting a first deploy, and the two access-denied pages - which are the surfaces where a visitor is most stuck.
- If the application sets a
Content-Security-Policy, ShinyHub adds the switcher'ssha256script hash to it and nothing else. A policy that forbids scripts outright ('none') is honoured by skipping the injection, never by relaxing the policy.
Set it to false to leave application pages without it. Off is absent rather
than idle: no page is rewritten, and the endpoint the switcher reads its list
from is not served at all.
Response compression¶
R and Python Shiny serve their pages and dependencies uncompressed. A typical
application page pulls over a megabyte of JavaScript and CSS (Bootstrap, jQuery,
shiny.js, widget libraries), which gzip shrinks about four-fold. ShinyHub
gzip-encodes responses for every browser that accepts it: application pages and
their assets, the dashboard, and the API.
On by default. What it compresses, and what it leaves alone:
- Text formats only:
text/*, JavaScript, JSON, XML, SVG, WebAssembly, and uncompressed font formats. Images,woff2, archives and other binary formats are already compressed and pass through untouched. - Bodies under 1 KiB, responses the application already encoded, partial
(
206) responses,HEADrequests, andCache-Control: no-transformresponses are sent as-is. - WebSocket connections are not gzip-encoded; their messages are compressed separately (see WebSocket compression).
- Server-sent events (
text/event-stream) are never compressed, so each event is delivered the moment it is written. Other streamed responses stay streamed: every flush from the application reaches the browser immediately. - A compressed response turns a strong
ETaginto a weak one, because the encoded bytes differ from the original. Conditional requests keep working, so a returning visitor still gets304 Not Modifiedfor unchanged assets. - Every response whose encoding depends on the browser carries
Vary: Accept-Encoding, so a shared cache never serves gzip to a client that did not ask for it.
Behind a reverse proxy that compresses as well, leave it on: the proxy sees
Content-Encoding and passes the response through rather than compressing it
twice. Turn it off only if you would rather not spend ShinyHub's CPU on it.
WebSocket compression¶
A Shiny session sends every rendered output over its WebSocket: a table of a few thousand rows is hundreds of kilobytes of JSON per update. R Shiny's server (httpuv) never compresses WebSocket messages, so on a slow or metered link each update travels at full size. ShinyHub compresses them on the application's behalf.
On by default. How it works:
- When the browser offers
permessage-deflate(every current browser does) and the application answers the upgrade without negotiating any extension, ShinyHub accepts the offer itself. The application keeps sending and receiving plain messages; ShinyHub compresses what it sends and decompresses what the browser sends. - An application that negotiates compression itself, such as Python Shiny, is left alone and its WebSocket bytes are relayed untouched.
- Messages under 256 bytes, messages that do not get smaller, fragmented messages, and messages over 16 MiB are sent uncompressed. Each message is compressed on its own, so ShinyHub keeps no compressor state per connection between messages.
- A compressed message from the browser may be at most 16 MiB compressed and
64 MiB decompressed; a larger one closes the connection with code
1009.
Set it to false to relay every WebSocket byte-for-byte.
Result cache¶
Each app gets a disk directory its replicas, workers, and scheduled jobs share
for computed results, and R apps use it for bindCache automatically. See
Result cache.
storage:
app_cache_dir: /var/lib/shinyhub/app-cache # SHINYHUB_APP_CACHE_DIR
app_cache_max_mb: 1024 # SHINYHUB_APP_CACHE_MAX_MB; 0 turns the cache off
Unset, app_cache_dir is an app-cache directory beside app_data_dir, so
the minimal server above caches in /var/lib/shinyhub/app-cache with no extra
key. The cache is disposable: leave it out of backups.
Environment overrides¶
Most configuration keys have an environment variable, named
SHINYHUB_<UPPER_SNAKE_CASE>. For example:
export SHINYHUB_BASE_URL=https://hub.example.com
export SHINYHUB_APP_ORIGIN=https://apps.example.com
export SHINYHUB_AUTH_SECRET="$(openssl rand -hex 32)"
export SHINYHUB_RUNTIME_DOCKER_DEFAULT_MEMORY_MB=512
Prefer environment variables or a secrets manager for credentials such as OAuth client secrets and database passwords.
The names are a fixed list, and a name that is not on it is only warned about¶
The variables are read by name from an explicit list, not derived from the YAML
key at runtime, so the mapping is not always mechanical: server.base_url is
SHINYHUB_BASE_URL rather than SHINYHUB_SERVER_BASE_URL, while the listener
is SHINYHUB_SERVER_HOST and SHINYHUB_SERVER_PORT. Names are written next to
their key in
shinyhub.yaml.example
and on the page that documents the setting; take the name from there rather than
deriving it from the key. That file does not carry every name, so a key shown
there without one may still have a variable, server.host and server.port
being two such keys.
A SHINYHUB_* variable that is not on the list changes nothing: the server
still comes up healthy on the value the variable was meant to replace. It does
say so, though. Startup logs one warning per unrecognized name, with the name
ShinyHub thinks you meant when one is close enough:
WARN ignoring unrecognized environment variable; nothing reads it
name=SHINYHUB_PORT did_you_mean=SHINYHUB_SERVER_PORT
WARN ignoring unrecognized environment variable; nothing reads it
name=SHINYHUB_TOTALLY_MADE_UP
SHINYHUB_PORT is the classic one: it is not a name ShinyHub reads (the port
is SHINYHUB_SERVER_PORT), so setting it leaves the server on port 8080. It
warns rather than refuses to boot, because a shared environment may legitimately
carry a SHINYHUB_ variable meant for something else, so the warning is yours
to read.
The startup log states the address that actually took effect, which is the cheapest way to confirm an override landed:
Log level and format¶
Two variables have no configuration-file equivalent, because logging is wired before the config file is read:
export SHINYHUB_LOG_LEVEL=debug # debug | info (default) | warn | error
export SHINYHUB_LOG_FORMAT=json # json | text
The format defaults to text when stdout is a terminal and json otherwise,
so a service-managed server logs JSON without being told to.
auth.secret is the exception: prefer a file¶
A process environment is readable by any process running as the same user
(/proc/<pid>/environ on Linux, ps eww on macOS), and on the native runtime
every deployed app is such a process. auth.secret signs every session token
and derives the key encrypting every app's secret env vars, so it is the one
credential worth taking out of the environment:
install -m 600 /dev/null /etc/shinyhub/auth.secret
openssl rand -hex 32 > /etc/shinyhub/auth.secret
export SHINYHUB_AUTH_SECRET_FILE=/etc/shinyhub/auth.secret
unset SHINYHUB_AUTH_SECRET
Equivalently, auth.secret_file in the config file. The server reads it once at
startup, trims surrounding whitespace, and refuses a file that is group- or
world-readable. Setting both the file and SHINYHUB_AUTH_SECRET to different
values is an error, since one of them would silently win. While the secret still
comes from the environment on the shared-user native runtime, startup logs a warning.
This narrows one exposure; it is not a tenant boundary. See isolation.md for why the native runtime should not host mutually-untrusting tenants.
The opt-in Linux native app-user backend separates
app identities from the controller. Its setting is
runtime.native.broker_socket (SHINYHUB_RUNTIME_NATIVE_BROKER_SOCKET); the
same-UID limitations above apply when that setting is empty.
It remains opt-in for this release, including on new Linux installations.
Upgrades keep the existing backend until explicitly configured. A configured
broker that cannot be used stops startup; it never selects the shared-UID backend
as a fallback. See the default and migration policy.
Application logs and how long they are kept¶
An application's stdout and stderr are written to one file per replica run,
under <apps_dir>/<slug>/logs/replica-<index>-<run-id>.log. A run is one start
of one replica: every restart, redeploy, hibernate-and-wake, and watchdog
recovery opens a new file rather than appending to the previous one, so a run's
output is never mixed with another's.
Two separate limits apply, and only the second is configurable.
Within a run. The file is capped at 5 MiB. On reaching the cap it is renamed
to <file>.1 and a fresh file is opened, and only one such backup is kept, so a
single very chatty run retains its last 10 MiB or so and loses the rest. This
cap is a constant with no configuration key: an application that logs a request
per line at volume will lose its startup output.
Across runs. Maintenance keeps the newest runs per app replica slot and deletes the rest, database rows and files together:
The default is 20 runs per replica slot. -1 keeps every run, which is the
setting to reach for when you want a long forensic window on a quiet
application; 0 selects the default rather than deleting everything. Pruning
happens at maintenance.interval (and once at startup), and only completed runs
are eligible, so the run currently serving is never removed. On an HA data plane
the same setting governs the shared chunks as well; see
HA data plane.
Disk cost is bounded by the product of these numbers: at the defaults, at most about 200 MiB of logs per replica slot for an application that fills every file, and far less in practice, since most runs never approach the cap.
Browser session lifetimes¶
Browser sessions have a renewable validity window and a strict maximum age:
auth:
session_ttl: 1h # SHINYHUB_AUTH_SESSION_TTL
session_max_age: 12h # SHINYHUB_AUTH_SESSION_MAX_AGE
session_ttl is the time a signed browser token remains valid between
renewals. Visible dashboards and hosted app pages renew it every third of that
window, up to once every five minutes. Hosted pages use an app-local endpoint
that remains available when the app switcher is disabled or apps run on an
isolated origin. Background tabs pause renewal and verify their session when
they return. An expired session cannot be renewed.
session_max_age is measured from the original login and never slides.
Renewed JWTs and cookies expire at that deadline, even if their normal TTL
would extend beyond it. Signing in again reruns SSO group reconciliation.
Both settings accept durations from 1m to 720h (30 days), and
session_ttl must not exceed session_max_age. Zero and negative values are
rejected; neither limit can be disabled. Environment variables override YAML.
The defaults are one hour and twelve hours. Choose shorter limits for shared
devices or privileged deployments; longer limits reduce sign-in frequency but
delay mandatory SSO reauthentication.
These settings apply to local-password, GitHub, Google, and OIDC browser sessions. They do not change API/CLI credential expiry, support-session deadlines, or upstream forward-auth policy. On an isolated app origin, app activity renews that origin's cookie; it does not renew the separate dashboard cookie. Both retain the original login time and logout identity. Existing authenticated app WebSockets and streaming responses end at the maximum login age even without another browser request. Apps whose HTML or CSP prevents script injection or same-origin requests cannot run automatic renewal; their signed cookies still expire and the server still enforces the maximum age. See sessions and logout for background-tab, WebSocket, and identity-provider behavior.
Fleet run and development session retention¶
Two more maintenance: settings bound history unrelated to application logs,
pruned on the same schedule:
maintenance:
fleet_run_retention_count: 20 # SHINYHUB_FLEET_RUN_RETENTION_COUNT
development_session_retention_days: 90 # SHINYHUB_DEVELOPMENT_SESSION_RETENTION_DAYS
interval: 1h
fleet_run_retention_count keeps this many newest terminal runs per fleet and
deletes older ones. The default (0) keeps every run. A run still recorded as
an app's latest or last-successful fleet apply is kept regardless of its
rank, since fleet status reads those two rows directly; a run still in
progress is never removed either.
development_session_retention_days deletes ended, non-ephemeral development
sessions older than this many days. The default (0) keeps every session.
Ephemeral sessions are never affected by this setting: they are removed with
their app, not by this sweep.
Both settings share app_log_run_retention_count's convention: 0 is the
default and means keep everything; -1 also means keep everything, accepted
explicitly for an operator who copies the sibling setting's -1 and expects
the same result; any other negative value is rejected at startup rather than
silently treated as "keep all", so a typo like -3 fails loudly instead of
quietly disabling pruning.
Pruning happens at maintenance.interval (and once at startup), same as the
application log run pruning above.
Host capacity¶
The Overview shows measured app usage alongside host capacity for CPU and memory. Usage includes all reporting replicas in the selected scope, including replicas without enforced app limits. It excludes other processes on the host; it is not a whole-machine utilization reading. Memory is summed RSS and can count shared pages more than once.
App-limit checks are shown separately, with per-replica pressure alerts and coverage. Missing measurements, optional unset limits, unknown limit status, and unenforced limits have distinct recovery guidance. The host capacity remains visible even when app limits are smaller, or when no apps are running.
The size of the box is detected at startup and needs no configuration. Override it only when the detected number is wrong for your deployment:
host_capacity_cores also sets the effective CPU budget for parallel worker
admission during live updates and scheduled rolls. Kernel CPU quotas still cap
update admission when an override is set.
Worker requests, the CPU reserve and a per-app surge ceiling are configurable
under server.update_capacity. See update capacity.
Env vars: SHINYHUB_HOST_CAPACITY_CORES, SHINYHUB_HOST_CAPACITY_MEMORY_MB.
The startup log records what was found and which source supplied it:
Sources for cores_source are config (you set host_capacity_cores),
cgroup-quota (a container CPU limit binds below the host's core count), and
affinity (the cores this process may run on). For memory_source they are
config, cgroup-limit (a container memory limit binds below the host total),
and host-total (what the OS reports for the machine).
Detection can fail - a platform with no cgroup files and no readable total. When it does, that capacity is reported as unknown rather than as a host with none: the Overview then shows CPU and memory in use with no percentage and no meter, since a zero denominator would draw a full bar at any load. The startup log warns when memory specifically could not be read.
Two cases are worth an explicit override. Under runtime.mode: docker the
detected figures describe the shared box, not any one worker's container; those
applications normally carry enforced limits, which appear separately in
app-limit checks. The detected host capacity does not represent remote worker
capacity. And on a host ShinyHub shares with other services, the detected total
is the whole machine, so set these keys to the share you intend ShinyHub to
have if you want the panel scaled to that.
These keys are separate from server.render_capacity_cores
(Render pacing), which is a pacing budget rather
than a reporting scale, although both are detected the same way.
Scale-to-zero application tier¶
ShinyHub can retain each application replica as a private Scaleway Serverless Container while Scaleway scales its underlying instance to zero:
runtime:
tiers:
- name: serverless
runtime: scaleway_serverless
scaleway:
region: nl-ams
project_id: 00000000-0000-0000-0000-000000000000
namespace_id: 00000000-0000-0000-0000-000000000000
image: rg.nl-ams.scw.cloud/shinyhub/runner:latest
control_plane_url: https://hub.example.com
default_memory_mb: 512
default_mvcpu: 250
Set SCW_ACCESS_KEY and SCW_SECRET_KEY in the server environment, never in
YAML. Standard SCW_DEFAULT_PROJECT_ID and SCW_DEFAULT_REGION variables are
accepted too. See the Scaleway Serverless deployment guide
for the runner image, security boundary, lifecycle, and real-provider tests.
Client configuration is different¶
For client commands such as deploy, apps, and fleet, SHINYHUB_CONFIG
selects the local credentials file, not the server YAML. Automation can avoid a
credentials file by setting SHINYHUB_HOST and SHINYHUB_TOKEN.
Forward-auth browser logout¶
auth.forward_auth.logout_url optionally names the custom auth service's
browser logout endpoint (an HTTP(S) URL or same-origin path).
auth.forward_auth.logout_method is GET by default, or POST for an empty
browser form submission. The environment overrides are
SHINYHUB_FORWARD_AUTH_LOGOUT_URL and SHINYHUB_FORWARD_AUTH_LOGOUT_METHOD.
See Caddy browser logout and reconnect
for proxy routing, separate app-origin cleanup, and protocol requirements.
Without this URL ShinyHub still stays logged out until explicit reconnect;
it does not end the upstream authentication service's session.
Reload environment and retired generations¶
server.env_file names a private (0600) KEY=VALUE file re-read at startup and
before each reload. It supports known server environment settings, proxy
variables and UV index settings. See systemd for syntax,
precedence, deletion behavior and secret handling.
server.max_retired_lifetime defaults to 24h; use a positive duration to bound
preserved WebSocket sessions after handoff. Sessions receive close code 1012
when the limit expires. shinyhub status --config /path/to/shinyhub.yaml reports
retired generations and their sessions. See reload retirement
for legacy output owners and metrics.