Introduction
Why Site Gateway exists
Reverse proxies often expose powerful settings without explaining what they change. Site Gateway provides a visual, Caddy-powered control plane for static sites, proxy routes, redirects, raw TCP/UDP streams, HTTPS, health checks, access control, and recovery — covering everything from a single ZIP upload to a full homelab of proxied applications.
How this manual is organized
Each area below has an overview article (what it’s for and how to configure the common case) followed by a field reference article covering every advanced control, one at a time. Use the sidebar to jump straight to a section, or search for any field name, error message, or setting — search matches headings, body text, and field names together.
Novice path
Create one route, test it locally, then add a domain and TLS. Keep defaults until you have a reason to change them.
Expert note
Configuration is stored in SQLite under /data and every generated Caddy configuration is validated before reload — if validation fails, the previous working configuration stays active and the failure is explained in Gateway Events.
Getting started
From installation to your first route
Install the container with persistent /data storage, open the management port (8080 by default), and complete the administrator setup screen shown on first launch. Before publishing public domains, confirm DNS already points to this server and that ports 80 and 443 are free for Site Gateway to use.
Choosing your first route type
- Hosted Site: you have static files (a ZIP or a single
index.html) and want Site Gateway to serve them directly. - Proxy Host: you already have an application running somewhere — another container, a LAN device, another server — and want a domain and HTTPS in front of it.
- Redirect Host: you want a domain to simply forward visitors to a different address.
- Streaming Host: you need to forward a raw TCP or UDP port (SSH, Minecraft, a game server) with no domain and no HTTPS involved.
Example
Publish a ZIP on a direct port first so you can confirm it works over LAN, then add www.example.com once DNS and port forwarding are ready and Automatic HTTPS can issue a certificate.
Dashboard
What each panel is telling you
The Dashboard is a glance-and-go summary — every number and status on it links back to a full section elsewhere, so you never have to act on the Dashboard itself.
Metric strip
Counts of Hosted Sites, Proxy Hosts, and Certificates needing attention, plus a Throughput chip showing live requests in the last minute across every configured domain — click it to open the full Performance tab.
Live Health
- Reverse proxy / Certificates / Persistent storage: the original health tiles.
- Streaming ports: how many enabled Streaming Hosts are actually bound and listening, versus configured.
- Upstreams: how many Proxy Hosts are currently passing their health check.
Runtime & System
A live resource panel — CPU, Memory, Swap, Disk, Network, and Uptime — reading this container’s own cgroup v2 stats rather than host-wide numbers, so the percentages reflect what’s actually assigned to Site Gateway (CPU quota or pinned cores, an explicit memory limit if one is set, and so on), not the whole machine it happens to be running on. It refreshes automatically every few seconds while the Dashboard is open, including the live-requests count in the Throughput chip above it. This is the exact same panel shown on Administration → System, so the two can never disagree — what changed there updates here too. Version, database, and Public IP facts (rechecked automatically every 60 minutes) live on the System page now rather than the Dashboard; see that section below.
Scheduled Jobs
Background jobs shown as status tiles — upstream health checks, scheduled backups, log pruning, access-log import, the Public IP check, configuration drift check, the database integrity check, and the disk usage refresh — each showing its schedule and last result.
Needs Attention
Lists anything that needs a decision (a failing health check, an expiring certificate). Clicking an item jumps straight to it. The Configuration drift item is the exception — it has its own inline Resync now button so you can clear it without leaving the Dashboard. That button is administrator-only; a Standard User or Viewer sees the same drift warning but resolves it by asking an administrator, rather than a button that would fail for them. When nothing needs attention, the panel collapses to a single all-clear banner instead of an empty list.
Recent Activity
The last several configuration and operational events, with relative timestamps (“4 hours ago”). This is a shortcut, not a separate log — the same events are searchable in full under Logs → Gateway Events.
Hosted Sites
Overview: publish a static website
A Hosted Site serves files you upload directly — no separate application or container required. Use it for a static site, a single-page app build, documentation, or anything that’s just HTML/CSS/JS.
Creating a Hosted Site
- Name: the label shown in Site Gateway; it doesn’t need to match the domain.
- Primary domain Optional: leave blank for port-only LAN access, or set a hostname to serve the same files there once DNS is ready.
- Additional domains: one alias per line — every alias serves the same files under the same TLS settings as the primary domain.
- Port: the direct LAN port this site answers on. Must fall inside the configured port range (shown as a hint on the form, default
9000–9099) and not already be used by another site. - TLS: Automatic public HTTPS (default, requires a working domain and open ports 80/443), Internal HTTPS for trusted local devices, or HTTP only.
- Enable HSTS after HTTPS is verified: only turn this on once you’ve confirmed HTTPS works for every client — HSTS tells browsers to refuse HTTP entirely for this domain going forward, and that’s hard to undo quickly.
- Website files: upload a ZIP whose root contains
index.html (a single top-level folder inside the ZIP is automatically flattened), or upload a bare index.html file directly. Up to 250 MB.
Updating an existing site
Use Replace files from the card’s menu to upload a new ZIP or HTML file without recreating the site or losing its domain/TLS/health settings. Use Domain & TLS to change the domain, TLS mode, or any advanced setting below.
Expected behavior
Files are served immediately on the chosen port and, once configured, through the domain as well.
Hosted Sites
Advanced options and health monitoring
Expand Advanced options on the create or edit form for these controls:
- Access List: applies a reusable network or login restriction before any visitor reaches this site. Choose Public — no Access List to leave it open.
- Compression: Automatic zstd + gzip (default), gzip only, or Off.
- Request headers / Response headers: one
Name: value pair per line, up to 30 each. Request headers are added before Caddy processes the request; response headers are added to what visitors receive. - Apply HSTS to subdomains: adds
includeSubDomains to the HSTS header; only takes effect when HSTS itself is on and TLS isn’t HTTP only. - Custom Caddy configuration: expert-only raw Caddyfile lines appended to this site’s block, validated before reload. Lines that would touch the global config block, the admin API, storage, or
import/persist_config directives are rejected outright, since those could affect every other route on the gateway.
Monitoring this site
Hosted Sites can be health-checked the same way Proxy Hosts are: a Health-check path (default /), method (GET or HEAD), expected status (a code, list, or range such as 200, 200,204, or 200-499), a timeout in seconds (1–60, default 4), up to 3 retries, and a Monitor this site toggle. Turning monitoring off shows the card as “Monitoring paused” instead of running a periodic check.
Proxy Hosts
Overview: connect a local application
A Proxy Host puts a domain and HTTPS in front of something already running elsewhere — another container, a LAN device, or a remote service.
Creating a Proxy Host
- Name: the label shown in Site Gateway.
- Primary domain and Additional domains: same behavior as Hosted Sites.
- Forward to: the upstream address, e.g.
http://192.168.1.20:8123. Use the container name, LAN address, or application URL — no path or query string beyond a trailing slash. - Upstream pool Optional: found under Advanced options — additional
http(s):// targets, one per line, up to 10. When present, Caddy distributes requests across every healthy target instead of using the single Forward-to address alone, and the Advanced options’ Load balancing setting controls how. - TLS: Automatic public HTTPS, Internal HTTPS, Custom uploaded certificate, or HTTP only.
- Enable HSTS after HTTPS is verified.
Example
For Jellyfin at 192.168.1.20:8096, use domain jellyfin.example.com and forward target http://192.168.1.20:8096. Site Gateway checks the upstream continuously and Caddy manages an eligible public HTTPS certificate automatically.
Proxy Hosts
Advanced options, field by field
Most applications only need a domain, Forward-to target, and TLS choice. These controls are for applications with unusual paths, authentication needs, response codes, headers, or performance requirements.
- Access List: applies reusable login and network rules before the upstream is reached.
- Health-check path and method: the request Site Gateway makes when checking this application (path default
/; GET or HEAD). - Expected status: accepts a single code, a comma list, or a range —
200, 200,204, or 200-399. - Timeout in seconds: 1–60, default 4.
- Monitor this upstream: when off, the status shows “Monitoring paused” and no periodic request is made.
- Compression: Automatic zstd + gzip, gzip only, or Off.
- Custom Locations: send specific paths to a different upstream. One per line:
/api/* | http://192.168.1.20:3001 | strip or preserve — strip removes the matched prefix before forwarding, preserve keeps it. Up to 20 entries. - Request headers / Response headers: same
Name: value-per-line format as Hosted Sites. - Upstream TLS server name: an optional SNI name expected by the upstream certificate. Only meaningful when every upstream target uses
https:// — the field is disabled otherwise. - Ignore upstream TLS certificate errors: use only for a trusted internal HTTPS service with a self-signed or hostname-mismatched certificate; also requires an HTTPS upstream to take effect.
- Apply HSTS to subdomains.
- Custom Caddy configuration: same validation rules as Hosted Sites’ custom configuration. NGINX syntax is not supported — Site Gateway generates Caddyfile syntax.
Upstream pool: additional http(s):// targets, one per line, up to 10 — the same field described in the Overview, now editable here too on an existing Proxy Host, not just when first creating it. Once Upstream pool has any entries, Caddy uses only those targets — the single Forward-to address above is not automatically added to the pool alongside them, so include it as one of the pool lines too if it should keep receiving traffic.Load balancing: only takes effect once Upstream pool has 2 or more entries — Forward to is never counted toward this, per the note above. Random (Caddy’s own default) picks a target at random per request; Round Robin rotates through targets evenly; Least Connections sends each request to whichever target currently has the fewest active requests; IP Hash sends a given client’s requests to the same target each time (sticky sessions), useful for applications that keep session state on one backend. This only affects which upstream Caddy sends a request to — it does not change the separate Health-check settings below, which only drive Site Gateway’s own dashboard status.How to verify a change
Save one setting at a time, watch the card’s upstream status line, check Access Logs, and compare against a direct request to the application. If Caddy rejects a custom configuration, Site Gateway keeps the last known-good configuration active and shows the rejection reason.
Proxy Hosts
Custom uploaded certificates
Choosing Custom uploaded certificate as the TLS mode reveals two file fields: Certificate PEM and Private key PEM. Both are required together — Site Gateway verifies the private key’s public key actually matches the certificate before accepting the pair, and confirms the certificate’s Subject Alternative Names cover every domain configured on that Proxy Host. A certificate that doesn’t cover every alias is rejected rather than silently applied to only some of them.
Accepted files are stored under /data/certificates/custom and included in complete backups. Replacing a custom certificate later works the same way — upload both files again through the same field.
Redirect Hosts
Overview: move an address safely
A Redirect Host sends visitors from one domain straight to another, with no files hosted and no application behind it.
Fields
- Name.
- Source domain: the old address people currently use.
- Additional source domains: further aliases that redirect the same way.
- Destination: a complete
http:// or https:// URL to send visitors to. - Redirect type:
302 Temporary (default), 301 Permanent, 307 Temporary — preserve method, 308 Permanent — preserve method. - TLS: Automatic HTTPS, HTTP only, or Internal HTTPS — this governs the source domain, not the destination.
- Preserve path and query (on by default): when enabled,
old.example.com/library?id=2 becomes new.example.com/library?id=2 instead of always landing on the destination’s root. - Access List Optional: protects the source domain the same way it protects Hosted Sites and Proxy Hosts.
Choosing a redirect type
Use 301 or 308 only when the move is meant to be permanent — browsers and search engines cache these aggressively. Use 302 or 307 while you’re still testing the new destination.
Streaming Hosts
Overview: raw TCP/UDP port forwarding
A Streaming Host forwards a raw TCP or UDP port straight to another host and port — there’s no domain, no HTTPS, and no HTTP layer involved at all, unlike every other route type in Site Gateway. Use it for services that speak their own protocol directly over a port: SSH, a Minecraft or other game server, a VPN endpoint, or any similar TCP/UDP service.
The one prerequisite: publish the port first
Streaming Hosts listen for connections from inside the Site Gateway container itself — they are not routed through Caddy the way domains are. That means the incoming port must already be published on the container (added to your docker-compose.yaml or Unraid port mappings, with the container recreated) before you create the matching Streaming Host in the UI, or nothing outside the container will ever reach it.
Example docker-compose port mapping
To forward SSH (22) and a Minecraft server (25565):
ports:
- "22:22/tcp"
- "25565:25565/tcp"
Creating a Streaming Host
- Name.
- Incoming port: 1–65535. Cannot be the admin port, 80, 443, a port already inside the Hosted Sites port range, or a port already used by another Streaming Host.
- Forward to: a plain
host:port address, e.g. 192.168.1.20:25565. No http:// — this is a raw socket forward, not a web address. - TCP / UDP: enable one or both. At least one must stay checked.
- Monitor this target: runs a TCP reachability probe against the forward address every check cycle, even for UDP-only streams (UDP itself has no reliable way to “ping” a service).
Streaming Hosts
How the forwarding actually works
TCP is a full one-to-one relay: every inbound connection gets its own fresh outbound connection to the forward target, and the two are piped together in both directions. Closing or erroring either side tears down the other.
UDP is connectionless, so Site Gateway multiplexes many remote clients over one listening port by tracking a short-lived “session” per unique client address, each with its own outbound socket to the forward target. An idle session is cleaned up automatically after about a minute of inactivity.
Health monitoring
The monitor always performs a plain TCP reachability check against the forward address, with a 4-second timeout — this confirms the target host and port are reachable, not that the specific game or service protocol is fully healthy. Disabling monitoring shows the card as “Monitoring paused” rather than unreachable.
Practical examples
- SSH: incoming port
2222, forward to 192.168.1.30:22, TCP only. - Minecraft: incoming port
25565, forward to 192.168.1.20:25565, TCP (and UDP if the specific server/mod needs it — vanilla Minecraft is TCP-only).
Editing a Streaming Host
Changing the port, target, or protocol checkboxes restarts the listener immediately to apply the change; toggling Enable/Disable does the same.
Certificates
Overview: automatic HTTPS prerequisites
For Automatic HTTPS to succeed, a domain must resolve to your public address, inbound ports 80 and 443 must reach Site Gateway, and no other service (including another reverse proxy) can already own those ports on this host.
Domain readiness checks
- DNS: confirms the domain actually resolves, and to what address.
- HTTP / HTTPS: confirms Caddy itself is listening on ports 80/443 inside the container — this does not by itself prove the internet can reach you, only that the gateway is ready to answer if it can.
- TLS: reflects the certificate status for that domain (healthy, renewing soon, critical, expired, or “Waiting for Caddy,” meaning issuance hasn’t completed yet — not that anything is broken).
- Upstream (Hosted Sites and Proxy Hosts): the latest health-check result for that route — shown as a healthy status code, “Monitoring paused” if the check is disabled for that host, “Check pending” if it hasn’t run yet, or the actual failure if it has genuinely failed. Redirect Hosts have no upstream to check.
Check now
Forces an immediate re-check of every certificate, domain readiness result, and health probe instead of waiting for the periodic background check. Administrator-only — the button is hidden for Standard Users and Viewers, who see the same readiness and certificate results but can’t force an early check.
Novice workflow
Confirm DNS, forward ports 80 and 443, stop any competing proxy, then run Check now. Don’t troubleshoot an upstream application until the domain and HTTPS checks themselves are healthy.
Certificate health thresholds
See Certificates → Field reference for what Renewing-soon warning, Critical warning, and Stale health data actually control.
Certificates
Field reference and thresholds
Selecting a certificate’s row opens its details in a popup: status, valid-from date, issuer, every domain it covers, serial number, SHA-256 fingerprint, and when it was last detected — deliberately excluding private key material.
Status thresholds
Set from the Certificates page itself, via the Configure thresholds link above the table:
- Renewing-soon warning: days remaining before a certificate is flagged as renewing soon (8–120, default 30).
- Critical warning: days remaining before it’s flagged critical; must stay lower than the renewing-soon threshold (default 7).
- Stale health data: minutes before a displayed check is considered old and worth re-running (2–1440, default 10).
A status of mismatch means a custom certificate was uploaded for that route but its coverage doesn’t include every configured domain — upload a replacement covering all of them.
Access Lists
Overview: protect a route
An Access List restricts who can reach a Hosted Site, Proxy Host, or Redirect Host, by network address, by login, or both. Assign a saved list from that route’s Advanced options.
Fields
- Name.
- Allowed networks: one IP, CIDR range, or the literal
private_ranges per line. When set, every network not listed is denied — this is an allow-list, not a suggestion. - Denied networks Optional: evaluated before allowed networks and logins, so a denied entry always wins even if it would otherwise be allowed.
- Logins: add one or more username/password pairs directly on the Access List (passwords need at least 8 characters; leaving a password blank while editing an existing login keeps it unchanged).
- Groups: alternatively, let members of a Group (Administration → Users & Groups) authenticate with their own Site Gateway username and password instead of a separate Access-List-only login. A disabled Group (Administration → Users & Groups) stops granting access immediately, even though it still appears assigned here — see Users & Groups for details. Assigning Groups is an administrator-only action: a Standard User can still fully manage everything else on an Access List, but this field is replaced with a note pointing them to an administrator, since Groups themselves live entirely inside Administration.
At least one rule — a network rule, a denied-network rule, or a login — is required before the list can be saved.
Assigning and inspecting
Use a route’s Advanced options to assign an Access List to it, or use the Access List’s own View assigned hosts menu action to see everywhere it’s currently in use. An Access List can’t be deleted while anything still references it — unassign it from every host first.
Users & Groups
Overview: control who can change the gateway
Every account has a role. Roles work on two independent questions: can this account see and use Administration (System, Users, Groups, Backups, API Access, Logs & Retention, Danger Zone) at all, and can it change Hosted Sites, Proxy Hosts, Redirect Hosts, Streaming Hosts, and Access Lists (everyone who’s signed in can already view those, along with the Dashboard, Certificates, Performance, and Logs pages).
- Administrator: the only role with any access to Administration — System, Users, Groups, Backups, API Access, Logs & Retention, and Danger Zone are entirely invisible to the other two roles, not merely read-only. Also the only role that can run a certificate/domain check, resync gateway configuration after drift, or assign Groups to an Access List.
- Standard User: can create, edit, delete, and enable/disable Hosted Sites, Proxy Hosts, Redirect Hosts, Streaming Hosts, and Access Lists — including a list’s network rules and login credentials. Cannot open Administration in any form, and within an Access List, cannot assign Groups (that control is replaced with a note pointing to an administrator), since Groups are themselves an Administration-only concept.
- Viewer: read-only across everything a Standard User can see — Dashboard, Hosted Sites, Proxy Hosts, Redirect Hosts, Streaming Hosts, Access Lists, Certificates, Performance, and Logs — with no create, edit, delete, or toggle controls anywhere. Like Standard, Administration is entirely out of view for a Viewer, not just non-editable.
Creating a user
- Display name.
- Username: 3–64 characters, letters/numbers/
._-, must be unique. - Role.
- Temporary password: at least 8 characters — share it securely and have the person change it after their first sign-in.
Managing an existing user
An administrator can change a user’s role from the card’s role dropdown, reset their password, archive them (a reversible soft-disable distinct from deleting), or delete them outright. Delete and Change icon live under the card’s “•••” menu, matching Hosted Sites and Proxy Hosts; role, password reset, and archive stay as visible buttons. You cannot disable, archive, delete, or change the role of your own account — another administrator has to do that — and Site Gateway always keeps at least one active Administrator, refusing any action that would leave zero. Resetting a user’s password here does not disable their two-factor authentication if they have it enabled — see My Account for how 2FA works. If a user is locked out of their own 2FA (lost authenticator, no recovery codes left), an administrator can disable it for them from the card’s “•••” menu — Disable 2FA appears there only when that user currently has 2FA enabled. This clears their authenticator, secret, and any unused recovery codes; they can set 2FA up again afterward if they choose to. The action is logged to the Audit log, since it removes a security control from someone else’s account.
Groups
A Group is simply a named set of users. Its only purpose is authentication: assign a Group to an Access List so its members can log in with their own Site Gateway credentials instead of a separate Access-List-only login.
Every Group has its own enable/disable toggle, separate from deleting it. Disabling a Group immediately stops it from granting access through any Access List it’s assigned to — the assignment itself is untouched and still shows as assigned, but its members can no longer authenticate through it until the Group is re-enabled. This is a common surprise: disabling a Group is not the same as archiving it for later cleanup, it has an immediate access-control effect. If the Group is currently assigned to at least one enabled Access List, disabling it now asks for confirmation first, naming exactly which Access List(s) will stop authenticating that Group’s members — the same pattern already used when disabling an Access List that protects active hosts.
Audit history
Administration includes an Audit log — a searchable, filterable, immutable record of who did what, filterable by outcome (success/failed) and free-text search across the user, action, and target. Audit entries can’t be edited or deleted.
My Account
Managing your own profile, password, and two-factor authentication
My Account is available to every role — Administrator, Standard User, and Viewer alike — and only ever affects your own account. It sits in the sidebar next to Administration and Documentation.
Profile
Shows your display name, username, and role. These are read-only here; an administrator changes them from Administration → Users.
Changing your password
Enter your current password once, then your new password twice. This works for every role — previously, only an administrator could change a user’s password (Administration → Users → Reset password), which meant every routine password change had to go through an admin. My Account closes that gap for everyone’s own account.
Two-factor authentication (2FA)
Optional and off by default for every account. When enabled, signing in requires your password plus a 6-digit code from an authenticator app (or a recovery code), using the standard TOTP algorithm (RFC 6238) — any authenticator app works, not a Site Gateway-specific one.
Enabling 2FA
- Choose Enable two-factor authentication.
- Scan the QR code with your authenticator app, or enter the shown key manually.
- Enter the 6-digit code it generates to confirm setup.
- Save the 10 recovery codes shown immediately afterward — each works once, and this is the only time they’re shown in full.
Signing in with 2FA enabled
After your username and password are accepted, you’re prompted for a code. Enter the current 6-digit code from your authenticator app, or one of your unused recovery codes if you don’t have the app available. A wrong code shows an inline error without sending you back to the username/password screen.
Disabling 2FA, or regenerating recovery codes
Both require re-entering your current password as confirmation. Regenerating recovery codes immediately invalidates the previous set.
An administrator resetting your password does not disable your 2FA — you’ll still need your authenticator app or a recovery code at your next sign-in. Only you can turn off your own 2FA, from My Account.
Administration
System
A read-only operations and diagnostics page — what’s configured, what’s running, and what this deployment can do. The only things you can actually change here are the Docker container-picker toggle and the action buttons; everything else is status.
Live resource panel
The same hero panel shown on the Dashboard — CPU, Memory, Swap, Disk, Network, and Throughput — reading this container’s own cgroup v2 stats (not host-wide numbers), so pinning or limiting the container changes what these percentages are measured against. CPU is measured against a real --cpus quota when one is set, pinned cores (--cpuset-cpus) when there’s no quota, or the host’s full core count as a last resort — the detail line under the number says which one applies. Swap only shows a percentage when the container has a real --memory-swap limit; otherwise it shows bytes in use with "Unlimited — shares host swap" rather than implying a cap that isn’t there. Disk compares against the full /data volume by default, or against an assigned allowance if DATA_DIR_LIMIT_GB is set on the container — useful when /data lives on a share or pool with other things on it, since the percentage then reflects what Site Gateway itself has written, not the whole volume’s usage; going over that assigned allowance shows over 100% and turns red rather than silently capping. Every stat with a percentage — CPU, Memory, Swap, Disk — turns amber at 75% and red at 90%, both the number itself and the bar beneath it, so a stat under strain is visible at a glance rather than something you have to read the exact figure to notice. The panel refreshes automatically every few seconds while this tab is open, and every signed-in user can see it, not just administrators.
Environment & integrations
Shows whether the Docker socket is mounted (and, if so, the toggle that lets Proxy and Streaming Hosts pick a running container as their target — moved here from Gateway Defaults) and whether BACKUP_PASSWORD is configured on the container (the actual "Encrypt scheduled backups" toggle it enables stays on the Backup & Restore page, next to the setting it drives).
If you’ve mounted /var/run/docker.sock and this still shows "not detected," it’s almost always a permissions issue rather than a missing mount. The socket is typically owned root:docker on the host with mode 660, but Site Gateway runs as the unprivileged PUID/PGID you set, not root. The container’s entrypoint handles this automatically at startup — while still root, it reads the socket’s actual group off the mount and adds the app user to it before dropping privileges — so a fresh container start after adding the mount should be enough; this detection only runs once at boot, so an existing running container needs to be restarted (not just have its mount added) to pick it up.
Security status
Read-only flags for whether ADMIN_PASSWORD or SESSION_SECRET are still on their built-in defaults, and whether ACME_EMAIL is set.
Gateway sync
Current configuration-drift status and a persistent Resync now control — the same action available inline on the Dashboard’s Needs Attention list, always available here too.
Scheduled jobs and storage
A table of background jobs with their schedule and last result, and a per-folder breakdown of what Site Gateway itself is storing under /data (sites, backups, certificates, logs, database). Total host disk capacity and free space are shown on the live resource panel’s Disk stat above, not repeated here.
Version
Site Gateway and Caddy versions, container uptime, database engine/status/size, and the gateway’s current Public IP (rechecked automatically every 60 minutes, prep work for future Dynamic DNS support) — alongside the dashboard access URL, data directory, and configured site port range that were already here. These moved from the Dashboard when its Runtime/System panel became the live resource hero panel above, so operational and version facts about the deployment now live in one place instead of being split across two pages. Uptime here refreshes on the same few-second cadence as the hero panel above it, rather than only when this page’s other details are refetched.
Reload & restart
Reload gateway config re-applies the current configuration to Caddy with no downtime and is always available. Restart application stops and restarts the whole application — it only becomes available when the Docker socket is mounted and the container’s own restart policy (checked via the Docker Engine API) is always, unless-stopped, or on-failure; without a qualifying restart policy, the container would not come back on its own, so the button stays disabled with an explanation instead.
Administration
API Access
Issue bearer tokens so scripts and integrations can call the Site Gateway API without signing in interactively. A token acts as the administrator who issued it — it can do anything that administrator could do through the API, scoped as described below — and its full value is shown to you only once, at creation.
Creating a token
Use the Create token button (same shared button used to create users, groups, and hosts elsewhere in Administration). You’ll re-enter your own administrator username and password to confirm, then set:
- Token name: a label to tell tokens apart later — name it after what will use it (for example, “Home Assistant integration”).
- Scope: Full access can read and change configuration; Read-only is restricted to GET requests only.
- Expires after: optional — a number of days after which the token stops working on its own. Leave it empty for a token that never expires.
After creation, the token’s full value is displayed exactly once in a “copy it now” dialog — only its hash is stored, so if you close that dialog without copying it, the value can’t be retrieved again and you’ll need to issue a new token.
The token list
Tokens are shown as cards, the same tile layout used for Hosted Sites and Groups, with a status bar above summarizing how many are active, revoked, full-access, and read-only at a glance — the Full access/Read-only counts only tally active tokens, so they stay consistent with the Active/Revoked split next to them. Each card shows the token’s name, its prefix (enough to identify it without exposing the full secret), its scope, who issued it and when, and when it was last used (or “Never used”) plus its expiration date if one was set. Each card also has a “•••” menu, matching Hosted Sites, Groups, and every other tile — Change icon lives there, and Revoke token too when the token is still active.
Revoking a token
Revoking is permanent — Site Gateway does not support re-enabling a revoked token, and there is no way to delete one outright. If you need it again, issue a new one. A token is also revoked automatically, along with every other token the same administrator issued, if that administrator’s account is disabled or their password is changed — this keeps a token from outliving the credentials that vouched for it.
Deleting a revoked token isn’t supported on purpose: even though it can no longer authenticate, its record (who issued it, when, its scope, and when it was cut off) stays part of the accountability trail, the same reasoning behind the Audit log never allowing entries to be edited or deleted. If the list gets long, use the Hide revoked toggle in the token summary bar to focus on active tokens without losing that history.
Administration
Gateway Defaults: handling unknown addresses
Controls what happens when a visitor reaches Site Gateway on HTTP using a hostname that isn’t configured. (Unknown HTTPS hostnames are always rejected outright, regardless of this setting, since serving anything else would need a certificate Site Gateway doesn’t have — and issuing a misleading one would be worse.)
Response modes
- Themed route-not-found page (404) — the safest public default.
- Gateway ready page (200) — useful while confirming HTTP routing during initial setup.
- No response — close connection.
- Redirect elsewhere: set a destination URL, redirect code, and whether to preserve the requested path and query.
- Custom HTML: administrator-authored markup, served exactly as written with no sanitization — up to 250,000 characters.
The themed page’s heading and explanation text are also editable here, independent of which mode is active. It displays the Site Gateway icon and wordmark, matching the branding used throughout the rest of the app.
Live preview
Configuration drift detection
Every 10 minutes (and once shortly after startup), Site Gateway compares Caddy’s live running configuration against what your saved routes would currently generate. If they disagree — for example after a manual edit outside the app, or a Caddy restart that didn’t pick up the latest reload — a “Configuration drift” item appears on the Dashboard’s Needs Attention list with its own inline “Resync now” button, which simply re-runs the normal save-and-reload path and clears the flag; it does not change any of your saved settings. The first time drift is detected, it’s also recorded as a Gateway Events entry.
Administration
Backup & Restore
Every place you create a backup — scheduled or the manual “Create backup” dialog — asks for a Backup type. A Configuration only backup contains a consistent SQLite snapshot of every route, user, group, Access List, and setting, plus a portable JSON export of the same data. A Complete backup (the recommended default) adds uploaded Hosted Site files, icons, the default-site page, and certificates (both managed and custom).
Scheduled backups
- Enable scheduled backups.
- Backup type: Complete (the recommended default) or Configuration only. If scheduled backups are enabled while Configuration only is selected, a warning appears explaining that Hosted Site files, icons, and certificates won’t be included.
- Schedule: Daily, Weekly, or Monthly, plus the hour of day to run.
- Keep: how many scheduled backups to retain (1–100, default 7) — older ones beyond this count are deleted automatically after each run.
- Include logs.
- Encrypt scheduled backups: uses the container’s
BACKUP_PASSWORD environment value. This checkbox is disabled with an explanation if BACKUP_PASSWORD isn’t currently set on the container — it can’t be turned on until that value exists. If it was previously enabled and BACKUP_PASSWORD was later removed from the container’s environment, it stays checked but shows a warning instead of failing silently at the next scheduled run — set the variable again (and restart the container) to resolve it.
Manual backup, encryption password
The optional backup password field on this page is used only for manually created backups and for restoring an encrypted archive — it is never stored by Site Gateway. A manually created backup is saved to /data/backups and appears in the list below; it does not download automatically — use that entry’s Download button when you want a local copy.
Restore checklist
- Download or import the
.sgbackup archive (importing just stages the file — restoring is a separate, explicit action). - Supply its password if it’s encrypted.
- Choose Restore and allow validation to finish.
- Confirm hosts, certificates, and upstream health afterward.
Site Gateway verifies every file’s checksum and automatically creates a safety backup of the current state before restoring anything. If the restored configuration turns out to be invalid, it automatically rolls back to that safety backup rather than leaving the gateway in a broken state.
Configuration safety & updates
Site Gateway validates every generated Caddy configuration before reload and keeps the previous working configuration active if validation fails. Container updates are installed by pulling a new pinned image — create a backup first.
Administration
Logs & Retention
Set how many days of Access, Activity, Audit, Certificate, and Security records to keep (7–3650 days each) and whether automatic pruning is enabled. Prune Now shows exactly how many records in each category are eligible before you confirm, and Download Logs exports them.
Administration
Danger Zone
Two separate, deliberately distinct destructive actions — kept apart so a routine preference correction is never confused with a full rebuild. Both require re-entering your own administrator username and password, typing an exact confirmation phrase, and then confirming a second themed dialog by typing YES.
Restore Defaults
Confirmation phrase: RESTORE DEFAULT. Resets Gateway Defaults, backup schedule settings, and certificate-health thresholds back to their starting values. It does not remove any hosts, uploaded files, users, groups, Access Lists, certificates, logs, or backups.
Factory Reset
Confirmation phrase: FACTORY RESET. Deletes everything under /data — every host of every kind, uploaded files, certificates (managed and custom), logs, backups, icons, users, and settings. Docker-mounted files outside /data are untouched. The container returns to the initial setup screen without needing a manual restart. Because backups themselves live under /data/backups, they’re deleted too — recovery is only possible from a backup taken beforehand and stored elsewhere (downloaded, or on separately mounted storage).
When to use a backup instead
If you want to undo a recent change while keeping the rest of the installation intact, restore a backup — Factory Reset is not a rollback tool.
Logs
Access Logs and Gateway Events
Access Logs
Every request Caddy handles, with domain, path, response status, latency, and upstream outcome. Filter by host or by status-code range (2xx/3xx/4xx/5xx). Sensitive query-string values — tokens, secrets, passwords, session identifiers, API keys, credentials — are redacted before they’re ever stored, regardless of filter settings.
Gateway Events
Configuration and operational changes, filterable by severity (Normal/Warnings/Errors) and by category (certificate, health, authentication, backup, configuration, or system). Like Access Logs above it, the column header row stays pinned in place while the table scrolls.
Example
Filter Access Logs for a 502, then compare the target address against a direct LAN request to the same upstream to isolate whether the problem is the gateway or the application itself.
Performance
Throughput by domain, over time
Built entirely from the same request data already collected for Access Logs — no new logging or extra overhead, just a different view of it.
Filters
Domain narrows the Trend chart to one host (default: all domains combined). Range sets the Trend window — Last hour, 3, 6 (default), 12, or 24 hours, or 3 or 7 days.
Trend
Request volume over the selected range, bucketed into 15-minute (up to 24h) or hourly (3–7 days) points.
Per-route table
One row per domain that has received traffic, sorted by 24-hour volume. The column header row stays pinned in place while the table scrolls, so the column each figure belongs to is always visible on longer lists.
- Last hour / Last 24h: request count for that window.
- Avg. response: the mean response time across every request to that domain in the last 24 hours — a fixed 24h window regardless of the Range filter above, and a straight average, so a handful of slow outliers can pull it up more than most visitors actually experience.
- Top paths: a per-domain “View” popout listing the top 10 most-requested paths on that domain in the last 24 hours, with request counts.
- Unconfigured chip: marks a domain in this table that doesn’t match any currently configured Hosted Site, Proxy Host, Redirect Host, or Streaming Host. This table is built straight from Caddy’s raw access log with no cross-reference against your configured hosts, so it reflects every Host header Caddy has ever seen — including scanning and bot traffic aimed at hostnames that were never set up here. Those requests fall through to the Default Site handler, which only ever serves a static page and never proxies anywhere, so an unconfigured entry here — even with meaningful traffic volume — is not a sign that an unconfigured site is actually being served. Use the Hide not configured checkbox above the table to filter these rows out and focus on domains you’ve actually set up; it resets to unchecked each time the page reloads.
Common Interface Controls
Menus, toggles, and role gating
The same card language is used throughout Hosted Sites, Proxy Hosts, Redirect Hosts, Streaming Hosts, Access Lists, Groups, and Users, so learning one area transfers directly to the next.
The three-dot menu
Contains actions that change or inspect a card: Edit opens the full form, kind-specific extras appear where relevant (Replace files on Hosted Sites, View assigned hosts on Access Lists), and Delete removes the record after a confirmation.
The toggle switch
A slide switch, separate from the menu, turns a route or account on or off without deleting its saved configuration — useful during maintenance or testing when you expect to reuse the exact same settings shortly after.
Who can use each control
Administrators can manage everything. Standard Users can manage Hosted Sites, Proxy Hosts, Redirect Hosts, Streaming Hosts, and Access Lists, but not Users, Groups, Settings, or Backups. Viewers can inspect information but cannot create, edit, disable, assign, or delete anything — their menus and toggles are hidden entirely. This is enforced on the server independently of what the interface shows, so hiding a button is a convenience, not the actual security boundary.
Update notifications
While signed in, Site Gateway checks every 60 seconds whether a newer version has been deployed. If so, a small banner appears with Refresh and Dismiss — Refresh reloads the page to pick up the new version; Dismiss hides the banner, but it reappears on the next check if you’re still on the old version. This only matters for a tab left open across a deploy; closing and reopening the tab, or signing in fresh, always loads the current version automatically.
Icons
Changing a card’s icon
Every Hosted Site, Proxy Host, Redirect Host, Streaming Host, Access List, Group, and User can have its own icon. Open the picker from a card’s icon tile or its “Change icon” menu action.
- Search by service name: type at least 2 characters (e.g.
Jellyfin, Plex) to search a large built-in icon catalog and pick a match. - Upload a custom image: PNG, JPEG, WebP, GIF, or SVG, up to 2 MB, stored locally under
/data/icons. Uploaded SVGs are checked for embedded scripts or external references before being accepted. - Image URL: paste a direct
https:// image link instead of uploading a file. - Use two-letter fallback: clears any icon and reverts to initials derived from the name.
If a custom icon URL ever stops loading, the card automatically falls back to showing initials instead of a broken image.
Troubleshooting
When HTTPS is not detected
Confirm public DNS actually points to this server, that router/firewall forwarding reaches ports 80 and 443, and that NGINX Proxy Manager or another reverse proxy isn’t still holding those ports. Then check Certificates and Logs → Gateway Events for the specific rejection reason. Site Gateway cannot request a public certificate while another gateway is receiving the ACME challenge on its behalf.
A route rejected its configuration
Check the error shown on save — it names the specific problem (duplicate address, invalid upstream, malformed custom configuration, certificate/TLS issue) rather than a generic failure, and the previous working configuration stays active while you fix it.
A Streaming Host isn’t reachable from outside
This is almost always the port not being published on the container yet — see Streaming Hosts → Overview for the docker-compose/Unraid port mapping requirement.
A user is locked out after enabling two-factor authentication
If they still have an unused recovery code, they can sign in with it in place of the 6-digit code. If not, an administrator can disable that user’s 2FA from Administration → Users — open the locked-out user’s “•••” menu and choose Disable 2FA. The user can sign in with just their password afterward and set 2FA up again whenever they’re ready.
- 
+ 