From 8f4420fd0e60533874f8864742350c7622926412 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 24 Feb 2026 12:38:58 +0000
Subject: [PATCH] docs: document nginx trailing-slash requirement for
 livekit-jwt-service

When using an external nginx (e.g. on a separate host) to reverse-proxy
the LiveKit JWT Service at a path prefix, the nginx location block MUST
include a trailing slash.

Without it: `location ^~ /livekit-jwt-service` + `proxy_pass .../;`
replaces `/livekit-jwt-service` with `/`, producing `//get_token`
(double slash). Go's net/http issues a 301 redirect to normalize the
path. Element Call follows the redirect to the wrong URL, fails to get a
JWT token, and the call establishes at the Matrix signaling level but
without any audio or video.

With trailing slash: `location ^~ /livekit-jwt-service/` replaces the
prefix correctly, producing `/get_token` with a single slash.

The same trailing-slash rule applies to the livekit-server location
block to avoid path issues for any sub-paths.

The built-in Traefik setup is unaffected (uses stripprefix middleware).

https://claude.ai/code/session_01SbRgWsRDKpTZ2TTbWDhtEB
---
 ...onfiguring-playbook-livekit-jwt-service.md | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/configuring-playbook-livekit-jwt-service.md b/docs/configuring-playbook-livekit-jwt-service.md
index eaf3be171..94ba3ab3b 100644
--- a/docs/configuring-playbook-livekit-jwt-service.md
+++ b/docs/configuring-playbook-livekit-jwt-service.md
@@ -16,3 +16,42 @@ Take a look at:
 
 - `roles/custom/matrix-livekit-jwt-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/custom/matrix-livekit-jwt-service/templates/env.j2` for the component's default configuration.
+
+## Using with an external nginx reverse-proxy
+
+If you use nginx (running on a separate host or outside Docker) to reverse-proxy the LiveKit JWT Service, the location block **must include a trailing slash** after the path prefix.
+
+The service runs on `/livekit-jwt-service` by default (set via `matrix_livekit_jwt_service_path_prefix`). nginx rewrites paths using the `proxy_pass` URI via string replacement: without the trailing slash, `location ^~ /livekit-jwt-service` combined with `proxy_pass http://BACKEND_HOST:PORT/;` replaces `/livekit-jwt-service` with `/`, turning `/livekit-jwt-service/get_token` into `//get_token` (double slash). Go's `net/http` server then issues a 301 redirect to normalize the path, which prevents Element Call from obtaining a LiveKit JWT token and causes calls to connect at the signaling level but without audio/video.
+
+**Correct nginx configuration:**
+
+```nginx
+# Note the trailing slash in location — required to avoid the double-slash path bug
+location ^~ /livekit-jwt-service/ {
+    proxy_pass http://MATRIX_SERVER_HOST:8091/;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+}
+```
+
+Similarly, when reverse-proxying the LiveKit Server's HTTP/WebSocket port:
+
+```nginx
+# Note the trailing slash in location — required for correct path rewriting
+location ^~ /livekit-server/ {
+    proxy_pass http://MATRIX_SERVER_HOST:7880/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+```
+
+The playbook's built-in Traefik reverse-proxy handles path stripping correctly using its `stripprefix` middleware, so this only affects setups using an external nginx.