Reverse Proxy

The native proxy access mode is designed for an HTTPS reverse proxy and GearBeacon running on the same host, with the backend bound to loopback. Owner authentication remains required. Use a dedicated hostname at its root path; the browser/API routes are rooted at /.

Configure the native backend

Save equivalent values in the browser's access settings, or seed a new process with:

GEARBEACON_ACCESS_MODE=proxy
GEARBEACON_BIND_HOST=127.0.0.1
GEARBEACON_PUBLIC_BASE_URL=https://gearbeacon.example.com
GEARBEACON_COOKIE_SECURE=1

Replace the documentation hostname with one you control. Restart to apply access/bind changes. Existing saved application settings take precedence over environment defaults. Configure DNS, a valid TLS certificate, and firewall restrictions independently; do not expose port 8787 beyond loopback in this setup.

GearBeacon accepts forwarded host, protocol, and client-address headers only from a loopback connection in proxy mode. Forwarded authorities must match configured allowed authorities. An HTTPS public URL enables secure cookies; trusted HTTPS responses receive HSTS. GEARBEACON_ALLOWED_ORIGINS contains explicit additional origins when needed, not a wildcard workaround for an incorrect proxy hostname.

Caddy example

With DNS/certificate issuance arranged for your hostname:

gearbeacon.example.com {
    reverse_proxy 127.0.0.1:8787
}

Caddy's HTTP reverse proxy preserves the incoming Host and supplies forwarded host/protocol/address headers. Use its documented TLS configuration for your deployment and trust only intended upstream proxies if another proxy sits in front. See the official reverse-proxy reference.

Nginx example

Inside the HTTPS server block for your configured hostname, with certificate/key settings already defined:

location / {
    proxy_pass http://127.0.0.1:8787;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $remote_addr;
    client_max_body_size 256m;
}

This single-proxy example replaces client-supplied forwarded addresses. The body limit accommodates GearBeacon's maximum recovery-import request; use a smaller deliberate limit if large imports are not needed. The location block does not configure TLS or an HTTP-to-HTTPS redirect by itself. See the official header directive and body-size directive.

Standard Docker bridge deployments

Container loopback belongs to the container, not the host. Changing the supplied bridged container to proxy mode with a loopback bind would make it unreachable through normal port publishing. A host proxy connecting through a published Docker port also does not appear as a loopback client inside the container.

For the supplied Compose topology, keep private mode inside the container, preserve the host's loopback-only published port, and run the HTTPS proxy on that host. Configure GearBeacon's HTTPS public URL and secure cookies. Have the proxy preserve the public Host and restrict all direct access to the backend.

This uses owner authentication and HTTPS at the proxy, but GearBeacon's private mode does not trust forwarded headers; client-address reporting reflects the connection peer rather than the original browser. It is a different trust configuration from native proxy mode. A separate proxy container also cannot use the host's 127.0.0.1 as though it were its own loopback; plan the topology explicitly rather than copying the native example unchanged.

Verify before relying on remote access

1. Open the HTTPS hostname and complete owner sign-in.
2. Confirm that reads and saves work without Host/origin/CSRF errors.
3. Check the configured public URL, secure-cookie state, and diagnostics in Settings.
4. Confirm the backend is reachable only by the intended proxy path.
5. Test a notification link and, if used, a recovery-import preview through the proxy.

For rejected hosts, login loops, or failed imports, use Troubleshooting. Preserve authentication, certificate validation, and exact-origin checks when correcting configuration.