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, HTTPS, health checks, access control, and recovery.

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 generated Caddy configuration is validated before reload.

Example

Publish a ZIP on a direct port first, then add www.example.com after DNS and port forwarding are ready.

Getting started

From installation to your first route

Install the container with persistent /data storage, open port 8080, and sign in with the administrator credentials supplied to Docker. Before publishing public domains, make sure DNS points to this server and ports 80 and 443 are free.

Hosted sites

Publish a static website

1. Open Hosted Sites and choose New hosted site.
2. Give the site a name and unused direct-access port.
3. Upload an index.html or ZIP whose root contains index.html.
4. Add a domain only when DNS is ready; choose Automatic HTTPS for public service.

Expected behavior: the files are served immediately on the chosen port and, when configured, through the domain.

Proxy hosts

Connect a local application

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 and Caddy manages eligible public HTTPS certificates automatically.

Certificates

Automatic HTTPS prerequisites

The domain must resolve to your public address, inbound ports 80 and 443 must reach Site Gateway, and another proxy cannot own those ports. “Not detected” means Caddy has not yet stored a certificate; review gateway events and DNS before retrying.

Health diagnostics

Understand what failed

Open Certificates and choose Check now to test DNS resolution, the gateway listeners, stored certificate coverage, and proxy upstream health. Expand a certificate for its non-secret details. Administrators can download a redacted support report when asking for help; it intentionally excludes credentials, cookies, private keys, secrets, and raw expert configuration.

Access Lists

Protect a route

Use private_ranges to allow standard LAN address ranges, or enter exact IP/CIDR values one per line. Add a login when the visitor must also authenticate. Assign the saved list from the Proxy Host’s Advanced section.

Redirect Hosts

Move an address safely

Use 301 or 308 only when the move is intended to be permanent; browsers can cache them. Use 302 or 307 while testing. Enable Preserve path and query when old.example.com/library?id=2 should become new.example.com/library?id=2.

Default site

Handle unknown addresses

The themed 404 is the safest public default. Gateway ready confirms HTTP routing during setup, No response closes unmatched HTTP connections, Redirect sends visitors elsewhere, and Custom HTML serves administrator-provided markup. Unknown HTTPS names still require their own valid route and certificate.

Backups

Back up before an update

A configuration backup contains a consistent SQLite snapshot and portable recovery data. A complete backup also contains hosted files, local assets, and certificate storage. Backups are stored in /data/backups; advanced installations can mount separate storage directly at that path.

Restore checklist

Recover with confidence

1. Download or import the .sgbackup archive.
2. Supply its password if it is encrypted.
3. Choose Restore and allow validation to finish.
4. Confirm hosts, certificates, and upstream health.

Site Gateway verifies file checksums and creates a pre-restore safety backup. If the restored Caddy configuration is invalid, it attempts to recover the previous state automatically.

Logs

Investigate requests and gateway events

Access Logs show domains, paths, response status, latency, and upstream outcomes. Gateway Events record configuration and operational changes.

Example

Filter for a 502 or failed upstream event, then compare the target address with a direct LAN request.

Administration · Users & Groups

Control who can change the gateway

Administrators manage users, roles, groups, and audit history. Standard Users perform permitted management tasks; Viewers are read-only.

Example

Create a Viewer for monitoring and a Standard User for routine route changes.

Administration · Gateway Defaults & Danger Zone

Preferences and destructive actions

Gateway Defaults control unknown HTTP responses, backup scheduling, and certificate thresholds. Restore Defaults changes preferences only. Factory Reset deletes all data under /data and returns to initial setup.

Example

Keep the themed 404 in production and create a complete backup before any factory reset.

Proxy Hosts · Advanced options

Why the advanced controls exist

Most applications work with only a domain, Forward to target, and TLS choice. Advanced options are for applications with unusual paths, authentication boundaries, response codes, headers, certificates, or performance needs.

What each control changes

• Access List: applies reusable login and network rules before the upstream is reached.
• Health-check path and method: tells Site Gateway what request to make when checking the application.
• Expected status: accepts a code, list, or range such as 200, 200,204, or 200-399.
• Timeout and retries: control how long a check waits and how many additional attempts are made.
• Compression: controls whether Caddy negotiates gzip or zstd for responses.
• Custom Locations: sends paths such as /api/* to a different upstream and can strip or preserve the path.
• Request and response headers: add metadata required by an application or browser.
• Upstream TLS server name: supplies the SNI name when the upstream certificate expects a hostname.
• Trust an unverified upstream certificate: permits internal HTTPS with an untrusted certificate; use only on a trusted network.
• HSTS: tells browsers to use HTTPS for future requests; enable only after HTTPS is reliable.
• Custom Caddy configuration: an expert escape hatch for supported Caddy directives, validated before reload.

Who, where, when, and why

Who: experts operating applications with documented proxy requirements. Where: the Advanced options panel for one Proxy Host. When: only after the basic route works. Why: to solve a known requirement rather than guessing at settings.

Practical example: Jellyfin

Use http://192.168.1.20:8096 as the upstream, leave the health path at /, keep the default expected range, and enable HSTS only after public HTTPS works. If an internal HTTPS service uses a private certificate, set its upstream SNI name and consider the unverified-certificate option only when the LAN is trusted.

How to verify

Save one change at a time, watch the card’s upstream status, inspect Access Logs, and compare the result with a direct request to the application. If Caddy rejects a custom configuration, Site Gateway retains the last known-good configuration.

Administration · Danger Zone

Reset preferences or rebuild from zero

This page contains the two actions with the greatest impact in Site Gateway. They are intentionally separate so a routine preference correction cannot be confused with a destructive rebuild.

Restore Defaults: what it is for

Restore Defaults returns gateway preferences to their known starting values: the Default Site response, page heading and explanation, redirect behavior, backup schedule, and certificate-health thresholds. It does not remove hosts, uploaded files, users, groups, Access Lists, certificates, logs, or saved backups.

Factory Reset: what it is for

Factory Reset removes Site Gateway data under /data, including routes, hosted content, users, groups, Access Lists, certificates, logs, backups, icons, and settings. Files mounted outside /data are not touched. Use it for a lab rebuild, a clean handoff, or recovery from an intentionally abandoned configuration—not to undo one route.

Who should use these actions

Only an Administrator should use them. Standard Users and Viewers should not see or operate destructive controls. The server verifies the signed-in administrator, the entered username, and the password before showing the final confirmation.

What happens when you click the button

Validation happens in order: username, password, confirmation phrase, then a second themed dialog requiring YES. Cancel clears every field and changes nothing. Restore Defaults applies immediately and refreshes the page. Factory Reset clears the data, recreates the initial bootstrap state, shows a countdown, and returns to the first-install login/setup flow without requiring a manual container restart.

When to use a backup instead

If you want to undo a recent change while keeping the rest of the installation, create or restore a complete backup. Factory Reset is not a rollback tool; it intentionally removes the recovery material stored under /data/backups.

Practical examples

• Your Default Site explanation is confusing: use Restore Defaults.
• You are moving the container to a new owner: create a complete backup, verify it, then use Factory Reset.
• A route stopped working: inspect Logs and restore the route or backup; do not factory-reset first.

After a Factory Reset

Open the management URL, sign in with the installation administrator credentials, and complete the initial administrator setup. Recreate or restore your hosts, certificates, users, groups, and Access Lists only after confirming the empty gateway responds correctly.

Common Interface Controls

Menus, status controls, and icons

The same card language is used throughout Hosted Sites, Proxy Hosts, Redirect Hosts, Access Lists, Groups, and Users so that learning one area transfers to the next.

What the three-dot menu is for

The three-dot menu contains actions that change or inspect a card. Edit opens the full form. Enable/Disable changes whether the route or control is active without deleting its saved configuration. Assignments shows which hosts use an Access List. Delete removes the record after a confirmation.

Who can use each action

Administrators can manage all cards. Standard Users see only actions allowed by their capability set. Viewers can inspect information but cannot create, edit, disable, assign, or delete configuration. Authorization is enforced by the server, not only by hiding buttons.

When to disable instead of delete

Disable a route during maintenance or testing when you expect to reuse its settings. Delete only when the route, assignments, and its configuration are no longer needed.

Changing a card icon

Select the card’s icon or choose Icon from its menu to open the icon picker. Search by service name, such as Jellyfin, then select a result. You can also upload a custom PNG, JPEG, WebP, or SVG when the service is not in the catalog. The interface scales icons into the same two-letter tile size and preserves the current initials as a fallback if an icon is removed or unavailable.

Practical examples

• Disable a Proxy Host while upgrading Plex, then enable it after the upstream responds.
• Assign one Access List to several hosts and inspect Assignments before changing its rules.
• Choose a Jellyfin icon for a Proxy Host; if the icon catalog is unavailable, its initials remain visible.

Backup and troubleshooting

Icons and assignments are included in complete backups. If a custom icon does not appear, verify the upload completed, refresh the card list, and confirm the file format is supported. Changing an icon never changes routing, TLS, or access behavior.

Hosted Sites · Field reference

What each Hosted Site field means

Name is the label you see in Site Gateway; it does not have to match the domain. Primary domain is the main hostname. Additional domains are aliases that serve the same files. Upload accepts a site folder or ZIP and expects index.html at the web root. Port is the direct LAN port and must be inside the configured range. TLS controls whether the domain uses automatic public HTTPS. HSTS should be enabled only after HTTPS has been tested on every intended client.

Novice example

Name the route “Family landing page,” use port 9100, upload the ZIP, browse to the LAN address, and add a domain later.

Expert example

Use additional domains for a canonical and legacy hostname while keeping one file tree. Complete backups preserve both the route metadata and uploaded files.

Certificates · Field reference

Read certificate health correctly

Each configured hostname receives its own readiness result. DNS shows whether the name resolves, HTTP and HTTPS show listener reachability, and TLS shows certificate coverage and status. Issuer identifies the authority, expiration shows remaining lifetime, and “Waiting for Caddy” means issuance has not completed—not that a certificate was already created.

Novice workflow

Confirm DNS, forward ports 80 and 443, stop competing proxies, then run the certificate check. Do not troubleshoot an upstream application until the domain and HTTPS checks are healthy.

Expert workflow

Use custom certificates for externally purchased or wildcard material under the custom certificate area. Keep Caddy-managed ACME material separate and protect private keys.

Advanced proxy settings

Start simple, expand only when needed

Custom Locations route selected paths to different upstreams. Request headers are sent upstream; response headers are returned to visitors. Health checks accept individual codes or ranges. Unverified upstream TLS and custom Caddy configuration are expert controls—change one item at a time and rely on validation feedback.

Troubleshooting

When HTTPS is not detected

Confirm public DNS points to this server, router forwarding reaches ports 80 and 443, and NGINX Proxy Manager or another service is not still using those ports. Then review Certificates and Logs → Gateway events. Site Gateway cannot request a public certificate while another gateway receives the challenge.