Skip to main content

Reverse Proxy Configuration

Weir is designed for a single-process, single-instance deployment. Production deployments should expose one canonical HTTPS origin.

WEIR_ENV defaults to production when unset, so an install behind a reverse proxy gets ASP.NET's production error handling (no developer exception page) without setting anything. development is for building Weir from source; a running install should never set it.

Trusted proxies​

Weir ignores X-Forwarded-For unless WEIR_TRUSTED_PROXY_IPS is configured:

WEIR_TRUSTED_PROXY_IPS=192.0.2.1,192.0.2.0/24

When the immediate peer is trusted, Weir uses the right-most untrusted address in X-Forwarded-For as the client key. Forwarded headers from untrusted peers are ignored.

Host header allow-list​

Weir answers only the addresses it recognises: an IP literal, localhost, a single-label name, a .local/.lan/.home/.home.arpa/.internal/.localdomain name, a host from WEIR_CORS_ORIGINS/WEIR_TRUSTED_BROWSER_ORIGINS, or an entry in WEIR_ALLOWED_HOSTS. If you reach Weir through a domain name — a reverse-proxy setup, typically — add it here.

A request whose peer is in WEIR_TRUSTED_PROXY_IPS skips this check — the proxy is the one deciding which domains reach Weir. Otherwise, list your reverse-proxy domain:

WEIR_ALLOWED_HOSTS=weir.example.com

A leading *. also allows its subdomains (WEIR_ALLOWED_HOSTS=*.weir.example.com). A request for an address not on this list gets a 400 naming the address it received, so a misconfigured proxy is easy to diagnose from the response itself.

WEIR_SESSION_COOKIE_SECURE defaults to auto: the sign-in cookie is marked HTTPS-only when a request arrives over HTTPS, either directly or through a proxy listed in WEIR_TRUSTED_PROXY_IPS that sends X-Forwarded-Proto: https. Behind a proxy that terminates HTTPS, setting WEIR_TRUSTED_PROXY_IPS is enough. Set WEIR_SESSION_COOKIE_SECURE=true only to force it. The Windows tray app is the exception: it always starts the server with WEIR_SESSION_COOKIE_SECURE=false.

Don't force it on an install you also reach over plain HTTP. The browser discards an HTTPS-only cookie on an HTTP page, so sign-in sends you straight back to the login page.

CORS​

Credentialed browser requests require explicit origins. Setting WEIR_CORS_ORIGINS=* is rejected at startup.

WEIR_CORS_ORIGINS is optional extra hardening for a same-origin setup too. Set it to the address you reach Weir at (for example https://weir.example) and browser posts are refused unless their Origin, or failing that their Referer, is in the list. It is off by default because a proxy that rewrites the Host header would otherwise be refused, and the CSRF token and X-Requested-With header already protect those requests.

For split-origin deployments (static site and API on different origins):

  • Use HTTPS everywhere
  • Set WEIR_CORS_ORIGINS to the real web origin
  • Set WEIR_TRUSTED_BROWSER_ORIGINS if stricter POST checks are needed
  • Set WEIR_SESSION_COOKIE_SAMESITE=none and WEIR_SESSION_COOKIE_SECURE=true: credentialed cross-origin requests need a SameSite=None; Secure cookie

Rate limiting​

Login and bootstrap rate limiting is process-local memory. This is correct only because the supported runtime is single-process. Multiple app processes would each have their own rate-limit buckets.