A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
docs: shorten the reverse proxy guide around rexctl
Hampus93aa824d04dc
diff --git a/fluxer_docs/src/content/docs/media-proxy/overview.md b/fluxer_docs/src/content/docs/media-proxy/overview.mdindex 12b569caf..3c766853d 100644--- a/fluxer_docs/src/content/docs/media-proxy/overview.md+++ b/fluxer_docs/src/content/docs/media-proxy/overview.md@@ -91,7 +91,7 @@ An operator can limit which web origins read media through CORS. `FLUXER_MEDIA_P| `report` | Every response is the same as under `off`, and each read `enforce` would refuse is logged || `enforce` | A read from an origin outside the allowlist returns 403 |-Under `enforce`, an `Origin` is allowed when it equals the serialised form of an entry in `FLUXER_MEDIA_PROXY_CORS_ALLOWED_ORIGINS` byte for byte. The desktop app origin `fluxer-app://app` is always allowed and needs no entry. Anything else is refused, including `null`, a repeated `Origin` header, and a value that is not ASCII. A refused read returns 403 on every read path, and the Media Proxy reads no object and fetches no external URL for it. [Media Proxy settings](/operator/configuration/#media-proxy-settings) defines how an entry is parsed and serialised.+Under `enforce`, an `Origin` is allowed when it equals the serialised form of an entry in `FLUXER_MEDIA_PROXY_CORS_ALLOWED_ORIGINS` byte for byte. The desktop app origin `fluxer-app://app` is always allowed and needs no entry. Anything else is refused, including `null`, a repeated `Origin` header, and a value that is not ASCII. A refused read returns 403 on every read path, and the Media Proxy reads no object and fetches no external URL for it.A read with no `Origin` is served without `Access-Control-Allow-Origin`. A browser sends no `Origin` for an `<img>` or a `<video>` without `crossorigin`, so those elements still load. An allowed read gets its own origin back in `Access-Control-Allow-Origin` on a media representation and on a 416. No error has CORS headers.@@ -101,7 +101,7 @@ Under `enforce`, every response to a `GET` or `HEAD` on a read path has `Vary: A`report` changes no response. The Media Proxy logs a warning with the reason `cors_origin_would_deny` for each read `enforce` would refuse.-The policy applies to a response the Media Proxy generates, and a shared cache in front of it answers a hit on its own. An entry stored while the policy was `off` holds `Access-Control-Allow-Origin: *` and a year of `Cache-Control`, and a foreign origin reading that URL gets both back until the entry goes. Purge `/attachments/` when you move the policy to `enforce`. [Caching in front of Fluxer](/operator/reverse-proxy/#caching-in-front-of-fluxer) states how.+The policy applies to a response the Media Proxy generates, and a shared cache in front of it answers a hit on its own. An entry stored while the policy was `off` holds `Access-Control-Allow-Origin: *` and a year of `Cache-Control`, and a foreign origin reading that URL gets both back until the entry goes. Purge `/attachments/` when you move the policy to `enforce`.A `static` or `relay` endpoint ignores the policy. The [upload relay](/media-proxy/upload-relay/) and the [operator and internal endpoints](/media-proxy/routes/#operator-and-internal-endpoints) are exempt from it. A method other than `GET` or `HEAD` on a read path returns 405 whatever its `Origin`.@@ -109,7 +109,7 @@ The reference self-hosted deployment leaves the policy `off`. An operator who tu## Signed attachment URLs-An operator can require a signature on every attachment read. `FLUXER_MEDIA_PROXY_ATTACHMENT_SIGNATURE_MODE` sets this signed attachment URL policy, and it defaults to `off`. The reference self-hosted deployment leaves it `off`, and turning it on takes a secret and the mode. The Media Proxy reads the mode once at start, and [Turning the signature policy on](/operator/reverse-proxy/#turning-the-signature-policy-on) gives the order to move it and a cache in front of it, and what each pairing of the two serves.+An operator can require a signature on every attachment read. `FLUXER_MEDIA_PROXY_ATTACHMENT_SIGNATURE_MODE` sets this signed attachment URL policy, and it defaults to `off`. The reference self-hosted deployment leaves it `off`, and turning it on takes a secret and the mode. The Media Proxy reads the mode once at start.| Value | Description || --- | --- |@@ -145,7 +145,7 @@ The Media Proxy reads the raw query string. It splits it on `&`, skips empty fie- `hm` does not verify against any configured secret.- The current time is at or after `ex` on an ordinary URL.-A shared cache in front of the Media Proxy must leave the signature parameters `ex`, `is`, `hm`, and `uc` out of its cache key, and must decode each parameter name before it compares it. A cache that keeps them stores a new entry every time the same object is signed again. [Caching in front of Fluxer](/operator/reverse-proxy/#caching-in-front-of-fluxer) states the rest of the rules.+A shared cache in front of the Media Proxy must leave the signature parameters `ex`, `is`, `hm`, and `uc` out of its cache key, and must decode each parameter name before it compares it. A cache that keeps them stores a new entry every time the same object is signed again.Every other parameter is ignored, and so is the order of the parameters. The signature is over `ex`, `is`, `uc`, and the percent-decoded storage key, and never over the host, the scheme, the port, or another parameter. Because `uc` is signed, an ordinary URL relabelled `uc=dp` does not verify, and neither does a data package URL with `uc` removed. One signed URL therefore reads every [transformation](/media-proxy/transformations/) and `download` variant of its object. Every percent-encoded spelling of the same key verifies the same way, and a key whose decoded bytes are not valid UTF-8 is refused.diff --git a/fluxer_docs/src/content/docs/media-proxy/responses-and-limits.md b/fluxer_docs/src/content/docs/media-proxy/responses-and-limits.mdindex 12399b7d3..89dfc2847 100644--- a/fluxer_docs/src/content/docs/media-proxy/responses-and-limits.md+++ b/fluxer_docs/src/content/docs/media-proxy/responses-and-limits.md@@ -124,7 +124,7 @@ No route sets `immutable`, `Expires`, `ETag`, or `Last-Modified` on a read respoOne read selects a shorter policy. Under the `report` or `enforce` [signed attachment URL policy](/media-proxy/overview/#signed-attachment-urls), an attachment read whose signature is valid gets `public, max-age=` the seconds left on that signature in both headers, so no entry outlives the URL that made it. A data package URL never expires, so it gets the one-day ceiling instead. Every other read, and every attachment read under `off`, keeps the year.-A one-year `max-age` is only safe where a purge path reaches every cache that stores media. With no `ETag` and no `Last-Modified` there is nothing to revalidate against, so a deleted or replaced object is served until its entry is purged or drops out. A cache with no purge path must set a shorter lifetime of its own instead. [Caching in front of Fluxer](/operator/reverse-proxy/#caching-in-front-of-fluxer) states how.+A one-year `max-age` is only safe where a purge path reaches every cache that stores media. With no `ETag` and no `Last-Modified` there is nothing to revalidate against, so a deleted or replaced object is served until its entry is purged or drops out. A cache with no purge path must set a shorter lifetime of its own instead.Every route-produced error response uses `Cache-Control: no-store`, and a successful `/_metrics` read uses it too. A 416 response, a successful upload relay response, and the empty-body method rejection of a registered path set no cache policy at all.diff --git a/fluxer_docs/src/content/docs/operator/reverse-proxy.mdx b/fluxer_docs/src/content/docs/operator/reverse-proxy.mdxindex e9cafcc6b..2257c70ec 100644--- a/fluxer_docs/src/content/docs/operator/reverse-proxy.mdx+++ b/fluxer_docs/src/content/docs/operator/reverse-proxy.mdx@@ -1,142 +1,41 @@---# SPDX-License-Identifier: AGPL-3.0-or-later-title: Behind your own reverse proxy-description: Serving a Fluxer instance from nginx, Caddy, Traefik, HAProxy, Apache, or a tunnel.+title: Use your own proxy+description: Put nginx, Caddy or another reverse proxy in front of your Fluxer instance.----:::tip[The Operator Pass is coming]-The [Operator Pass](https://fluxer.app/pass) gives you a direct line to the Fluxer team. It goes on sale in early November 2026 for $199 or €199, paid once. The price goes up on 1 January 2027. Pass holders get these perks for life.+By default, Fluxer uses ports 80 and 443 and gets its own certificate from Let's Encrypt. If another web server on the machine already uses those ports, Fluxer can serve plain HTTP on a local port for your proxy to forward to.-- A private channel in Fluxer Labs where the team answers questions about your instance-- The Operator role in Fluxer Labs-- An Operator Pass profile badge-- Invitations to test new features on your instance-- Your avatar and name on the Fluxer website, if you want+## Turn it on-The pass unlocks nothing in the software, and self-hosting stays free. If you have Visionary, you already have the pass.--We are grateful to everyone supporting the project through [Fluxer Plutonium](https://fluxer.app/plutonium) or [donations](https://fluxer.app/donate). All of our code is free and open source on [GitHub](https://github.com/fluxerapp/fluxer).-:::--Fluxer runs behind any proxy that terminates TLS and forwards WebSocket upgrades.--The stack ships Caddy and runs it by default on `80` and `443`. One extra Compose file stops that and publishes a single plain HTTP port. That port routes every path to the right internal service. The proxy in front forwards everything to it unchanged.--## Enable the overlay--`docker-compose.proxy.yml` ships next to `docker-compose.yml` and layers on top of it. Pass both files on every command:--```bash-docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d+```sh+rexctl proxy on```-Or set `COMPOSE_FILE` in `.env` once and keep typing plain `docker compose` commands:+Fluxer then listens on `127.0.0.1:8080`. To use another address or port, pass it with `--bind`:-```ini-COMPOSE_FILE=docker-compose.yml:docker-compose.proxy.yml+```sh+rexctl proxy on --bind 127.0.0.1:8081```-On a first install, `sh install.sh --tls proxy` writes that line and `FLUXER_EDGE_BIND` into `.env`. [Installer flags](/operator/get-started/#installer-flags) lists it with the rest.--The port binds `127.0.0.1:8080` by default. `FLUXER_EDGE_BIND` sets both the interface and the host port. Move the port when something else on the host already holds `8080`:--```ini-FLUXER_EDGE_BIND=127.0.0.1:8081-```--The container side stays `8080` whatever you set. A proxy on the host then points at `127.0.0.1:8081`, and a proxy on the stack's own Docker network points at `edge:8080`. Bind a routable address only when the proxy runs on another machine, and firewall the port to that machine:--```ini-FLUXER_EDGE_BIND=0.0.0.0:8080-```--Confirm the port answers before you configure anything in front of it:--```bash-curl -i http://127.0.0.1:8080/_health-```--`/_health` returns `200 OK` from the edge itself without reaching an upstream, so it is the health check to give your proxy.--## What every proxy must do--#### Terminate TLS and serve the hostname over HTTPS--With `FLUXER_PUBLIC_SCHEME=https` the admin CSRF cookie is `__Host-csrf_token`, which browsers accept only over HTTPS.--#### Keep TLS 1.2 enabled--The Android and iOS apps play video through a media library whose TLS stack offers only TLS 1.2. The rest of each app uses the system TLS stack. Behind a proxy that accepts only TLS 1.3 the apps sign in and load messages and images, but every video fails with "Could not play this video."+If your proxy runs on another machine, bind an address that machine can reach and only let the proxy connect to that port. You can also pass `--behind-proxy` to `rexctl install` to start this way, and `rexctl proxy off` goes back to Fluxer's own certificate.-Accept TLS 1.2 alongside TLS 1.3. TLS 1.2 can stay limited to ECDHE key exchange with AES-GCM or ChaCha20-Poly1305, which the apps support.+Your proxy can use `/_health` as its health check.-| Proxy | Setting |-| --- | --- |-| nginx | `ssl_protocols TLSv1.2 TLSv1.3;` |-| Caddy | `protocols tls1.2 tls1.3` |-| Traefik | `minVersion: VersionTLS12` |-| HAProxy | `ssl-min-ver TLSv1.2` |-| Apache httpd | `SSLProtocol -all +TLSv1.2 +TLSv1.3` |+## What your proxy needs to do-Caddy and Traefik accept both versions by default, so their rows apply only where a `tls` block or a TLS option already sets a floor. The HAProxy keyword goes on the `bind` line. On Cloudflare, keep Minimum TLS Version at 1.2 or lower. The bundled edge accepts both versions.--#### Forward WebSocket upgrades--The client connection is on `/gateway` and voice signalling is on `/livekit/*`. Both open as WebSocket upgrades. Check that the handshake completes through whatever is in front of the instance, with your own hostname in place of `chat.example.com`:--```bash-curl -sS -i --http1.1 --max-time 5 \- -H 'Connection: Upgrade' \- -H 'Upgrade: websocket' \- -H 'Sec-WebSocket-Version: 13' \- -H 'Sec-WebSocket-Key: AAAAAAAAAAAAAAAAAAAAAA==' \- 'https://chat.example.com/gateway?v=1&encoding=json' | head -1-```--The answer is `HTTP/1.1 101 Switching Protocols`. Confirm a real client connects as well, which covers the whole path including the query string.--#### Replace `X-Forwarded-For` with the real client address--Set the header from the connection address and discard whatever the visitor sent. Rate limits, IP bans and abuse detection all apply to the address that arrives in it.--#### Accept a request body above the attachment limit--Uploads pass through the proxy. Raise any default body limit, such as nginx's 1 MB, above the instance attachment limit.--#### Hold a connection open for an hour--The Gateway socket stays open for the life of a client session, so give idle and read timeouts an hour.--#### Pass `Sec-Fetch-Site` through untouched--Browsers send it, and the admin dashboard refuses a mutating request with a cross-site value.--#### Send no `Content-Security-Policy` of its own--The instance sends its own policy, and its nonce is what lets the web app boot. Browsers enforce every policy they receive.--Every worked configuration below meets all of these requirements.--## The public address--The variables below tell the instance the address browsers use. Fluxer reads neither `X-Forwarded-Proto` nor `X-Forwarded-Host`, so you keep these correct by hand:--```ini-FLUXER_DOMAIN=chat.example.com-FLUXER_PUBLIC_SCHEME=https-FLUXER_PUBLIC_PORT=443-```+- Serve your domain over HTTPS and accept TLS 1.2 as well as TLS 1.3. The mobile apps play videos with a library that only supports TLS 1.2.+- Forward WebSocket connections.+- Set `X-Forwarded-For` to the address the request came from, and drop any value the visitor sent.+- Accept request bodies of at least 512 MB for uploads.+- Keep idle connections open for an hour.+- Pass the `Sec-Fetch-Site` header through unchanged.+- Don't add a `Content-Security-Policy` header. Fluxer sends its own.-They stay `https` on `443` though the edge speaks plain HTTP on `8080`. Clients read every base URL from the discovery document the API builds from these values.--To serve on another public port, change `FLUXER_PUBLIC_PORT` alone. The proxy holds that port, and the overlay keeps the edge on `8080`.--Leave `FLUXER_PUBLIC_ORIGIN` commented out, or keep it consistent with all three settings. Conflicting addresses can break sign-in and setup. See [The public origin](/operator/configuration/#the-public-origin).+Forward every path and query string to Fluxer unchanged.## nginx-The `map` block makes `Connection` follow `Upgrade`. The snippet raises the body limit and the read timeout above nginx's own 1 MB and 60 seconds.-```nginxmap $http_upgrade $connection_upgrade {default upgrade;@@ -158,6 +57,7 @@ server {ssl_certificate /etc/letsencrypt/live/chat.example.com/fullchain.pem;ssl_certificate_key /etc/letsencrypt/live/chat.example.com/privkey.pem;+ ssl_protocols TLSv1.2 TLSv1.3;client_max_body_size 512m;@@ -178,373 +78,27 @@ server {}```-Set `X-Forwarded-For` from `$remote_addr`. `$proxy_add_x_forwarded_for` appends whatever the client sent, which puts an attacker-chosen address in front of the real one.+Use `$remote_addr` for `X-Forwarded-For`. `$proxy_add_x_forwarded_for` keeps the value the visitor sent, and anyone could then pretend to come from another address.## Caddy-An external Caddy needs one site block. It forwards WebSocket upgrades natively, requests the certificate itself, and applies no request body limit and no read timeout of its own. By default it ignores the inbound `X-Forwarded-*` headers from untrusted clients and writes its own, so there is no header line to add.-```caddychat.example.com {reverse_proxy 127.0.0.1:8080}```-Caddy trusts no proxy by default. If another proxy or CDN sits in front of it, configure Caddy's global `trusted_proxies` option and Fluxer's [trusted proxies](#trusted-proxies) so requests retain the real client address.--## Traefik--Traefik forwards WebSocket upgrades natively, and by default it strips inbound `X-Forwarded-*` headers from untrusted clients and writes its own. Leave `forwardedHeaders` alone unless another proxy sits in front of Traefik.--### File provider--Static configuration:--```yaml-entryPoints:- web:- address: ":80"- http:- redirections:- entryPoint:- to: websecure- scheme: https- websecure:- address: ":443"- transport:- respondingTimeouts:- readTimeout: 0s- idleTimeout: 3600s--providers:- file:- filename: /etc/traefik/dynamic.yml--certificatesResolvers:- letsencrypt:- acme:- email: [email protected]- storage: /etc/traefik/acme.json- httpChallenge:- entryPoint: web-```--`readTimeout` defaults to 60 seconds and covers reading the whole request including the body, so `0s` removes the bound and lets a large upload finish. `idleTimeout` defaults to 180 seconds, so raise it to an hour to hold the Gateway socket open.--Dynamic configuration in `/etc/traefik/dynamic.yml`:--```yaml-http:- routers:- fluxer:- rule: Host(`chat.example.com`)- entryPoints:- - websecure- service: fluxer- tls:- certResolver: letsencrypt-- services:- fluxer:- loadBalancer:- passHostHeader: true- servers:- - url: http://127.0.0.1:8080-```--### Docker labels--Traefik reaches the container over a shared Docker network, so the published port is not used. Keep the overlay applied anyway, or the instance takes `80` and `443` away from Traefik.--Put this in `traefik.compose.yml` next to the stack:--```yaml-services:- edge:- networks:- - fluxer- - traefik- labels:- traefik.enable: "true"- traefik.docker.network: traefik- traefik.http.routers.fluxer.rule: Host(`chat.example.com`)- traefik.http.routers.fluxer.entrypoints: websecure- traefik.http.routers.fluxer.tls.certresolver: letsencrypt- traefik.http.services.fluxer.loadbalancer.server.port: "8080"--networks:- traefik:- external: true-```--Then list all the files so every command picks them up:--```ini-COMPOSE_FILE=docker-compose.yml:docker-compose.proxy.yml:traefik.compose.yml-```--## HAProxy--One frontend, one backend, and the timeouts:--```haproxy-defaults- mode http- log stdout format raw local0- option httplog- timeout connect 5s- timeout client 1h- timeout server 1h- timeout tunnel 1h--frontend fluxer- bind :80- bind :443 ssl crt /etc/haproxy/certs/chat.example.com.pem alpn h2,http/1.1- http-request redirect scheme https unless { ssl_fc }- http-request set-header X-Forwarded-For %[src]- default_backend fluxer_edge--backend fluxer_edge- server edge 127.0.0.1:8080-```--`timeout client` and `timeout server` stop applying once a connection is upgraded, so `timeout tunnel` is what keeps the Gateway socket and LiveKit signalling alive. `set-header` replaces any header the client sent. `option forwardfor` appends to it. Give the frontend and the backend different names. HAProxy warns on a shared name and drops support for it in 3.3.--## Apache httpd--This configuration needs these modules: `mod_proxy`, `mod_proxy_http`, and `mod_headers`. Since 2.4.47 `mod_proxy_http` handles the WebSocket upgrade itself, so `mod_proxy_wstunnel` is not needed.+Caddy's defaults already do everything in the list above, and Caddy gets the certificate for your domain itself.-```apache-<VirtualHost *:443>- ServerName chat.example.com-- SSLEngine on- SSLCertificateFile /etc/letsencrypt/live/chat.example.com/fullchain.pem- SSLCertificateKeyFile /etc/letsencrypt/live/chat.example.com/privkey.pem-- LimitRequestBody 536870912- ProxyPreserveHost On- ProxyTimeout 3600-- RequestHeader set X-Forwarded-For "expr=%{REMOTE_ADDR}"-- ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600- ProxyPassReverse / http://127.0.0.1:8080/-</VirtualHost>-```+## Cloudflare-`upgrade=websocket` is the whole WebSocket configuration on 2.4.47 and later.+If Cloudflare proxies your domain, change these settings in the Cloudflare dashboard:-`RequestHeader set` replaces whatever the client sent, and the quotes around `"expr=%{REMOTE_ADDR}"` are required by the expression parser. `ProxyAddHeaders` is on by default and appends the connection address after that value. The edge reads the real address either way.--`LimitRequestBody` is 0 by default, which means no limit, but distribution packages and `<Directory>` blocks often set it lower. The 536870912 above is 512 MiB. `ProxyTimeout` and the `timeout=3600` parameter both bound the upstream connection, and an hour covers the Gateway socket.--## Cloudflare Tunnel--One ingress rule for the hostname, with the catch-all `cloudflared` requires under it:--```yaml-tunnel: fluxer-credentials-file: /etc/cloudflared/fluxer.json--ingress:- - hostname: chat.example.com- service: http://127.0.0.1:8080- originRequest:- connectTimeout: 30s- - service: http_status:404-```--When `cloudflared` runs as a container on the stack's Docker network, point it at `http://edge:8080`. The published port is then never used. Compose prefixes the network name with the project name, which the stack sets to `fluxer`, so the network is `fluxer_fluxer` and an external declaration names it in full:--```yaml-networks:- fluxer:- external: true- name: fluxer_fluxer-```--Cloudflare appends the visitor address to any `X-Forwarded-For` the visitor sent, so the header can arrive with a forged value in front of the real one. The edge reads the rightmost address that is not in `FLUXER_EDGE_TRUSTED_PROXIES`, which is the one Cloudflare appended. A Transform Rule that sets `X-Forwarded-For` to `cf.connecting_ip` removes the ambiguity.--Cloudflare caps a request body at 100 MB on Free and Pro, 200 MB on Business, and 500 MB on Enterprise, and answers 413 above the cap. The cap applies to tunnel traffic, and no `cloudflared` setting raises it. Keep the [`max_attachment_file_size`](/http-api/instance/#limit-keys) limit below the cap for your plan, in the admin dashboard under limit configuration. It defaults to 26214400 bytes for a non-premium account and 524288000 bytes for a premium one, which is above every cap below Enterprise.--A tunnel has the web app, API, Gateway, admin dashboard, media routes, and LiveKit signalling, but no LiveKit media.--## Nginx Proxy Manager--Add a proxy host with these values:--| Field | Value |-| --- | --- |-| Domain Names | The hostname `chat.example.com` |-| Scheme | Plain `http` |-| Forward Hostname / IP | `127.0.0.1`, or the `edge` container when both run in Docker |-| Forward Port | Port `8080` |-| Websockets Support | On, and required |-| Block Common Exploits | Off, because its request filtering rejects legitimate API traffic |-| SSL | Request a certificate, then turn on Force SSL and HTTP/2 Support |--In the Advanced tab:--```nginx-client_max_body_size 512m;-proxy_read_timeout 3600s;-proxy_send_timeout 3600s;-```--Nginx Proxy Manager appends to `X-Forwarded-For`, so the visitor's own value arrives in front of the real address. The edge takes the rightmost entry that is not in `FLUXER_EDGE_TRUSTED_PROXIES`, which is the one Nginx Proxy Manager appended. Users on a LAN or a VPN inside the default `private_ranges` are the exception and resolve to the forged entry, so narrow `FLUXER_EDGE_TRUSTED_PROXIES` to the proxy's address in that layout.--## What the single port routes--Forward every path and query string unchanged. The edge handles routing:--| Public path | Purpose |-| --- | --- |-| `/_health` | Edge health check |-| `/gateway`, `/gateway/*` | Gateway connections and health |-| `/api/*` | HTTP API |-| `/media/*` | Media and attachment delivery |-| `/livekit/*` | Voice signalling |-| `/admin`, `/admin/*` | Admin dashboard |-| `/web/*`, `/emoji/*`, `/libs/*`, `/avatars/*`, `/badges/*`, `/desktop/*` | Static assets |-| `/.well-known/fluxer` | Instance discovery |-| `/.well-known/apple-app-site-association`, `/apple-app-site-association` | Apple app association |-| `/.well-known/assetlinks.json` | Android app association |-| `/version.json` | Client version metadata |-| `/_geoip` | Client location lookup |--All other paths serve the web app. The admin path follows `FLUXER_ADMIN_BASE_PATH`, `/admin` by default.--Pass the query string on `/gateway` through untouched. Clients always send `?v=`, `?encoding=`, `?compress=` and `?stream=`, and `1` is the only version the Gateway accepts.--Apple and Google require the association files at those fixed paths for saved-password autofill and app links. A proxy that forwards all paths needs no extra rules. Include them explicitly if you use a path allowlist.--`/_metrics` on the API, Media Proxy, Gateway, and push service, plus `/_health/ready`, `/_health/drain`, and `/_health/undrain` on the Gateway, are gated to loopback and are unreachable through any proxy. The push service has no public path. The probes that work through a proxy are `/_health`, `/api/_health`, `/gateway/_health`, and `/media/_health`.--## Trusted proxies--`FLUXER_EDGE_TRUSTED_PROXIES` names the peer addresses whose `X-Forwarded-For` the edge believes. It defaults to `private_ranges`, which Caddy expands to `192.168.0.0/16`, `172.16.0.0/12`, `10.0.0.0/8`, `127.0.0.1/8`, `fd00::/8`, and `::1`, so a proxy on the same host or the same Docker network needs no change.--The edge resolves one client address per request and rewrites `X-Forwarded-For` to it on every upstream hop, so no service ever reads what a visitor sent. A peer outside the list becomes the client address, and the edge discards the header it sent. For a peer inside the list, the edge uses the rightmost header entry that is not itself trusted. A proxy that appends to the header therefore still passes on the real client address.--A proxy that reaches the instance from a public address is not trusted, so the edge discards its header and attributes every request to the proxy itself. That puts all your users in one rate limit bucket and one geolocation. Add the address, and list `private_ranges` too if you still need it:--```ini-FLUXER_EDGE_TRUSTED_PROXIES=private_ranges 203.0.113.10/32-```--`private_ranges` does not cover `100.64.0.0/10`, so a proxy reaching the instance over a Tailscale or other CGNAT tailnet address is untrusted and collapses every visitor onto that one address. Name the tailnet address of the proxy:--```ini-FLUXER_EDGE_TRUSTED_PROXIES=private_ranges 100.101.102.103/32-```--The edge accepts whatever a trusted peer sends. Anyone who can open a TCP connection from a trusted address can set `X-Forwarded-For` to any value and be recorded as that address, which defeats bans and rate limits and pollutes abuse detection. Keep the list down to the one address your proxy arrives from. That is also the only correct list on a LAN or VPN deployment, where a visitor whose own address falls inside a wider list is recorded under the proxy's address.--Find the address the edge sees a host-side proxy arrive from:--```bash-docker network inspect fluxer_fluxer -f '{{(index .IPAM.Config 0).Gateway}}'-```--The edge reads the variable at container start, so apply a change with `docker compose up -d`.--:::caution[Keep the plain HTTP port off the LAN]-`private_ranges` trusts the whole LAN. With `FLUXER_EDGE_BIND=0.0.0.0:8080`, any host on that network can impersonate any client address. Firewall the port to the proxy host.-:::--## Caching in front of Fluxer--Media reads are the only traffic worth caching, and the instance expects no cache in front of it. A cache that cannot follow every rule below must not store media.--#### Leave the signature parameters out of the cache key--`ex`, `is`, `hm`, and `uc` are the [signed attachment URL](/media-proxy/overview/#signed-attachment-urls) parameters. A key that keeps them stores a new entry every time the same object is signed again, which empties the cache of anything useful. Drop all four and keep every other parameter, because the rest select the representation.--Only drop them if your proxy also meets the next two rules. A key without them is the same key for a signed request and an unsigned one, so the signature check is the only thing between an unsigned request and the object.--#### Decode parameter names, and take the last value--Fluxer parses a query string with form URL decoding, so `%73ize` is the name `size` and `+` is a space. When a name repeats, the final value wins. A cache that compares raw bytes, or that keeps the first value, can be handed `%73ize=64` or `size=64&size=4096` and made to store one rendering under the key for another. Match both rules, or refuse to cache a request whose query string you cannot parse that way.--#### Check the signature before the cache lookup--A cache hit never reaches the instance, so the Media Proxy's own signature check never runs on one. Under the `enforce` [signed attachment URL policy](/media-proxy/overview/#signed-attachment-urls), verify the signature in the proxy before it looks in the cache. An nginx `access_by_lua_block` runs in the access phase, which is before the cache lookup. A proxy that cannot do that must leave `/attachments/` uncached, or it will serve an expired or forged URL from a warm entry.--#### Verify the same path the cache key is built from--Running before the cache lookup is not enough on its own. The check and the key must read the same spelling of the path, or a request the check skips still reaches the entry the key names.--In nginx that spelling is `$uri`, which nginx has already percent decoded, merged repeated slashes in, and resolved `.` and `..` out of. `$request_uri` is the raw bytes the client sent. A check that scopes itself on `$request_uri` never sees `//attachments/...`, `/attachments%2F...`, `/attachments/./...`, or `/x/../attachments/...` as an attachment read, while `$uri` and the cache key make all four the same object. Read `$uri` for the prefix test and for the storage key, take the query from `$request_uri`, and refuse a path whose `$uri` is not a usable storage key rather than passing it through.--The signature covers the decoded storage key, which is `$uri` without its leading slash.--#### Do not cache a range request without slice support--nginx removes `Range` from a request it may cache unless the slice module is built in, so a seek into a video pulls the whole object. Set `proxy_cache_max_range_offset 0`. A range request then reaches the instance untouched and is not stored, while an entry that is already warm still answers ranges from cache.--#### Wire up purge, and bound the entry lifetime anyway--Every media 200 is `public, max-age=31536000` with no `ETag` and no `Last-Modified`, so a cache never revalidates and a deleted object stays until its entry goes. Point `FLUXER_CACHE_PURGE_HTTP_ENDPOINT` at a receiver that clears your cache, and read the contract it must meet under [Cache purge](/operator/configuration/#feature-flags-and-development-switches). Give stored media a shorter lifetime of your own as well, because a purge that is lost is never sent again.--## Turning the signature policy on--`FLUXER_MEDIA_PROXY_ATTACHMENT_SIGNATURE_MODE` is the instance switch, and a proxy that verifies signatures has one of its own. Both sides name the same three states, `off`, `report`, and `enforce`. Apply an instance change with `docker compose up -d media-proxy`.--Turn the policy on in this order, and stop wherever a refusal appears that you did not expect:--1. Give `api`, `worker`, and `media-proxy` the same `FLUXER_MEDIA_PROXY_ATTACHMENT_URL_SECRETS_BASE64`, and give the proxy the same list. Every URL the instance returns is signed from here on, and nothing verifies yet.-2. Leave it there until the clients holding the unsigned URLs issued before step 1 have replaced them. A client refreshes a URL whose `ex` is absent or under an hour away, and one that has been open since before step 1 keeps its unsigned URLs until it reloads.-3. Set both sides to `report` and read the logs. Under `report` nothing is refused, and each read `enforce` would refuse is logged with its reason on the side that saw it.-4. Move the proxy to `enforce` once `report` is quiet.-5. Move the instance to `enforce`.--The proxy goes first because a cache hit never reaches the instance. Reversing steps 4 and 5 leaves every warm entry readable without a signature for as long as it lives.--From step 3 the instance caps `Cache-Control` on a read whose signature is valid at the time that signature has left, where `off` returns a year. `report` caps it too, so the entries stored during the dry run do not outlive the URLs that made them. A read `report` would refuse still returns a year, because there is no signature to cap it against. Entries stored before step 3 keep the year they were given.--### When the two sides disagree--| Proxy | Instance | What an attachment read gets |-| --- | --- | --- |-| `off` | `off` | Served. Neither side reads a signature |-| `off` | `report` | Served. The instance logs what `enforce` would refuse |-| `off` | `enforce` | Refused, unless a warm entry answers it without reaching the instance |-| `report` | `off` | Served. The proxy logs what its own `enforce` would refuse |-| `report` | `report` | Served. Both sides log |-| `report` | `enforce` | Refused, unless a warm entry answers it without reaching the instance |-| `enforce` | `off` | Refused at the proxy, before the cache lookup |-| `enforce` | `report` | Refused at the proxy. The instance logs nothing, because it is never asked |-| `enforce` | `enforce` | Refused at the proxy |--The two rows that serve a read the instance would refuse are the ones where the instance enforces alone. The instance is right and the cache is stale, and the entry answers until it goes, so pair an instance-first change with a purge of `/attachments/`.--A change to `FLUXER_MEDIA_PROXY_CORS_MODE` has the same problem and no step order that avoids it. An entry stored while the policy was `off` holds `Access-Control-Allow-Origin: *` and a year of `Cache-Control`, and the proxy replays both on every hit without asking the instance. The proxy's own signature check does not help, because it reads the signature and never reads `Origin`, so a foreign page holding one valid signed URL still reads the bytes cross-origin from a warm entry. Purge `/attachments/` when you move the CORS policy to `enforce`, the same purge step 5 needs.--`enforce` at the proxy alone covers every request that passes through it. Anything that can reach the instance another way is unchecked until the instance enforces too: a second cache, a health probe from outside the proxy, an internal service that reads an attachment URL directly, and a deployment running no proxy at all. Those are what step 5 covers, and what it can break.--Step 4 also ends the instance's own evidence. A read the proxy refuses never reaches the instance, so once the proxy enforces the instance logs nothing under `report` and its stream stays empty whatever it would have refused. Take step 5 on what step 3 showed, while both sides were still in `report`.--Both sides must hold the same secret list. A side missing a key refuses the URLs signed with it, so add a new key to both sides before the instance starts signing with it, and keep a retired key on both until the last URL it signed has expired. An ordinary URL expires within a day. A [data package URL](/http-api/messages/#data-package-attachment-urls) never does, and removing the key that signed it is what ends it.--With no secret list, `api` and `worker` return unsigned URLs, and a side in `enforce` refuses every attachment read. Never move a side to `enforce` before signing is on.--## Voice media does not use the proxy--LiveKit signalling goes through `/livekit/*` like everything else. WebRTC media does not touch the proxy at all:--- `7882/udp` is media.-- `7881/tcp` is the fallback when UDP is blocked.--Both ports are published directly by the stack and must reach the host. A proxy or tunnel in front of `443` does nothing for them.--Signalling can use a hostname other than `FLUXER_DOMAIN`. Two lines go in `.env`, beside `FLUXER_DOMAIN`. The first points clients at the new hostname, and the second lets the web app's Content-Security-Policy connect to it:--```ini-FLUXER_LIVEKIT_URL=wss://livekit.example.com/livekit-FLUXER_CSP_EXTRA_CONNECT_SRC=wss://livekit.example.com-```+- Turn Rocket Loader off. With it on, the web app shows a blank page.+- Don't let a Cache Rule store HTML pages, or people get an old version of the web app after you upgrade.+- Turn Bot Fight Mode off and don't add challenges for `/api/`, `/gateway` or `/livekit/`. The desktop and mobile apps can't solve a challenge.+- Set the SSL/TLS encryption mode to "Full (strict)" when Fluxer gets its own certificate.-The policy entry is the origin alone, with no port or path. The hostname needs a valid TLS certificate and must reach the `/livekit` route on the edge with WebSocket upgrades. The media ports above never belong in the policy, because WebRTC media is not governed by `connect-src`. A separate hostname is rarely needed, since media goes to the address LiveKit advertises, not to a hostname.+## Voice and video-`api` writes `FLUXER_LIVEKIT_URL` into the default voice server at start, and `app-proxy` builds the policy at container start. Apply the change with `docker compose up -d api app-proxy`. [Content Security Policy](/operator/configuration/#content-security-policy) has the other variables.+Voice and video calls don't go through your proxy. They connect to TCP port 7881 and UDP port 7882 on the machine directly, and both ports need to stay open. A tunnel such as Cloudflare Tunnel can't forward them, and an instance that you only serve through a tunnel has no voice or video calls.