From a753a3b2952408c510eb6ed962ba049a6ad22db0 Mon Sep 17 00:00:00 2001
From: thigg <thigg@users.noreply.github.com>
Date: Fri, 24 Apr 2026 08:14:07 +0200
Subject: [PATCH] Add nginx reverse-proxy example for Matrix RTC (#5086)

When fronting the playbook's integrated Traefik reverse-proxy with
another reverse-proxy (e.g. nginx), WebSocket traffic needs to be
forwarded to LiveKit Server at the `/livekit-server/` path for Matrix
RTC calls to work.

Adds a `/livekit-server/` location block to the nginx reverse-proxy
example, a section to the Matrix RTC docs explaining the requirement,
and cross-links between the two.
---
 docs/configuring-playbook-matrix-rtc.md    |  6 ++++++
 examples/reverse-proxies/nginx/matrix.conf | 21 +++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/configuring-playbook-matrix-rtc.md b/docs/configuring-playbook-matrix-rtc.md
index 9360202ad..fa9c29ee0 100644
--- a/docs/configuring-playbook-matrix-rtc.md
+++ b/docs/configuring-playbook-matrix-rtc.md
@@ -38,6 +38,12 @@ matrix_rtc_enabled: true
 
 In addition to the HTTP/HTTPS ports (which you've already exposed as per the [prerequisites](prerequisites.md) document), you'll also need to open ports required by [LiveKit Server](configuring-playbook-livekit-server.md) as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section.
 
+## Fronting the integrated reverse-proxy with another reverse-proxy
+
+If you're [fronting the integrated reverse-proxy webserver with another reverse-proxy](configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (e.g. nginx), it needs to forward WebSocket traffic for [LiveKit Server](configuring-playbook-livekit-server.md) at the `/livekit-server/` path. Without that, Matrix RTC calls will not work.
+
+See [`examples/reverse-proxies/nginx/matrix.conf`](../examples/reverse-proxies/nginx/matrix.conf) for an nginx example.
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records) and [adjusting firewall rules](#adjusting-firewall-rules), run the playbook with [playbook tags](playbook-tags.md) as below:
diff --git a/examples/reverse-proxies/nginx/matrix.conf b/examples/reverse-proxies/nginx/matrix.conf
index 69b32eb6f..c502100c8 100644
--- a/examples/reverse-proxies/nginx/matrix.conf
+++ b/examples/reverse-proxies/nginx/matrix.conf
@@ -22,6 +22,27 @@ server {
     # if you use e.g. Etherpad on etherpad.example.com, add etherpad.example.com to the server_name list
     server_name example.com matrix.example.com element.example.com;
 
+    # Required for Matrix RTC (WebSocket proxying to LiveKit Server).
+    # See: ../../../docs/configuring-playbook-matrix-rtc.md#fronting-the-integrated-reverse-proxy-with-another-reverse-proxy
+    location /livekit-server/ {
+        proxy_pass http://localhost:81/livekit-server/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        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;
+
+        # Long timeouts for persistent WebSocket connections
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+        proxy_buffering off;
+
+        access_log /var/log/nginx/matrix.access.log;
+        error_log /var/log/nginx/matrix.error.log;
+    }
+
     location / {
         # note: do not add a path (even a single /) after the port in `proxy_pass`,
         # otherwise, nginx will canonicalise the URI and cause signature verification