A custom domain

Reportforge on your own domain (https://reports.larkmere.example) is reportd behind your own reverse proxy and certificate, with publicURL set to that address. reportd has no domain setting of its own and serves no TLS: the proxy terminates HTTPS.

Setting it up

1. Point the name at the proxy and give the proxy a certificate for it (your own, or Let's Encrypt).
2. Proxy to reportd, keeping the Host header, and passing the client's address and scheme: X-Forwarded-For (or Forwarded, or X-Real-IP) and X-Forwarded-Proto.
3. Trust the proxy: set security.trustedProxies to its address or network, and security.clientAddressHeader if it doesn't send X-Forwarded-For (rate-limits.md uses the client address). Without it, reportd sees every request as the proxy's.
4. Set publicURL to the address people use: https://reports.larkmere.example. It can be set in the config file, with REPORTD_PUBLICURL, in setup, or under Admin → Settings (settings.md).

On Kubernetes, the Helm chart's Ingress is the proxy, and publicURL defaults to https://<ingress.host> (helm.md).

What follows publicURL

• Report links (report() and /l/<token>) in exported documents point there.
• Passkeys are bound to publicURL's domain: they work only there, and passkeys made on another domain don't (mfa.md). Without publicURL, or with an IP address, passkeys are off.
• Sign-in providers redirect back to <publicURL>/v1/auth/oidc/<id>/callback and post to <publicURL>/v1/auth/saml/<id>/acs; SAML's entity ID is under it too (sso.md).
• The licence's domains bind softly to publicURL's host: a mismatch is a warning (licence.md).

Changing it

Moving to a new domain changes all of the above at once. Admin → Settings warns before you save a new publicURL:

• everyone's passkeys stop working on the new domain, so people add them again there (their authenticator apps and recovery codes still work);
• each sign-in provider's redirect URI (OIDC) and the SAML entity ID and ACS must be changed at the provider to the new address, or sign-in through it fails;
• old report links keep pointing at the old address until they expire.

Keep the old name answering, redirecting to the new one, while those catch up.

When the address in use isn't publicURL

The Settings page warns when the browser reached reportd at another host than publicURL names: links, passkeys and sign-in providers use publicURL, so they won't match what people see. Reach reportd at publicURL, or change it to the address in use.