From 481132ec4c504884d83920469bb8bfbb911a0848 Mon Sep 17 00:00:00 2001
From: "William L. Thomson Jr." <w@wltjr.com>
Date: Tue, 23 Jun 2026 18:23:51 -0400
Subject: [PATCH] Document lighttpd configuration example from
 matrix.jaxlug.ngo

A contribution from the Jacksonville Linux Users Group Inc. in setting up
our Synapse Matrix protocol server matrix.jaxlug.ngo. While we mainly run
Apache, we had lighttpd on some VMs for letsencrypt purposes. Since there
was no documentation for lighttpd, we undertook the challenge.

We had to simulate the client/server URL end points in rewriting to a
json file, rather than a nifty way such as ngnix, although that might be
possible in lighttpd, vs our brute force crude url rewrite method.

Otherwise, this is a IPv4 and IPv6 solution running HTTP and HTTPS on both
with ultra fast socket backend communication between Synapse and lighttpd.
That does require each lighttpd and synapse to be members of each others
group or at least one, as they both need full read/write to the socket file.

This is just one of many contributions from the Jacksonville Linux Users
Group, Inc. aka, the JaxLUG. Cheers!
---
 changelog.d/19875.doc |  1 +
 docs/reverse_proxy.md | 73 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 changelog.d/19875.doc

diff --git a/changelog.d/19875.doc b/changelog.d/19875.doc
new file mode 100644
index 00000000000..6ab67a08a2f
--- /dev/null
+++ b/changelog.d/19875.doc
@@ -0,0 +1 @@
+Document lighttpd reverse proxy configuration example from matrix.jaxlug.ngo, a contribution from the JaxLUG, the Jacksonville Linux Users Group Inc..
diff --git a/docs/reverse_proxy.md b/docs/reverse_proxy.md
index 0e3303df57d..786c0fe4c9a 100644
--- a/docs/reverse_proxy.md
+++ b/docs/reverse_proxy.md
@@ -4,8 +4,10 @@ It is recommended to put a reverse proxy such as
 [nginx](https://nginx.org/en/docs/http/ngx_http_proxy_module.html),
 [Apache](https://httpd.apache.org/docs/current/mod/mod_proxy_http.html),
 [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy),
-[HAProxy](https://www.haproxy.org/) or
-[relayd](https://man.openbsd.org/relayd.8) in front of Synapse.
+[HAProxy](https://www.haproxy.org/),
+[relayd](https://man.openbsd.org/relayd.8) or
+[lighttpd](https://www.lighttpd.net/)
+in front of Synapse.
 This has the advantage of being able to expose the default HTTPS port (443) to Matrix
 clients without requiring Synapse to bind to a privileged port (port numbers less than
 1024), avoiding the need for `CAP_NET_BIND_SERVICE` or running as root.
@@ -312,6 +314,73 @@ relay "matrix_federation" {
 }
 ```
 
+### lighttpd
+```conf
+server.modules = (
+    "mod_rewrite",
+    "mod_redirect",
+    "mod_access",
+    "mod_setenv",
+    "mod_openssl",
+    "mod_proxy",
+    "mod_accesslog"
+)
+
+server.username      = "lighttpd"
+server.groupname     = "lighttpd"
+
+# leave commented out for proper IPv6 see below IPv4 0.0.0.0 & IPv6 [::]
+#server.use-ipv6 = "enable"
+
+ssl.pemfile = "/etc/lighttpd/cert+privkey.pem"
+ssl.ca-file = "/etc/lighttpd/fullchain.pem"
+
+$SERVER["socket"] == "0.0.0.0:80" { }
+$SERVER["socket"] == "0.0.0.0:443" { ssl.engine = "enable" }
+$SERVER["socket"] == "0.0.0.0:8448" { ssl.engine = "enable" }
+$SERVER["socket"] == "[::]:80" { }
+$SERVER["socket"] == "[::]:443" { ssl.engine = "enable" }
+$SERVER["socket"] == "[::]:8448" {  ssl.engine = "enable" }
+
+# both lighttpd and synapse need permissions for socket r/w
+$HTTP["url"] =~ "(/_matrix|_synapse/admin|/_synapse/client)" {
+    proxy.balance = "hash"
+    proxy.server = ( 
+        "" => ( 
+            "backend-socket" => (
+                "host" => "/var/lib/synapse/main_public.sock",
+                "port" => 0
+            )
+        )
+    )
+    proxy.forwarded = (
+        "for" => 1,
+        "proto" => 1,
+        "host" => 1,
+    )
+}
+# protect admin access IPv6 ULA only
+$HTTP["remoteip"] !="fd00::/8" {
+    $HTTP["url"] =~ "^/_synapse/admin/" {
+        url.access-deny = ( "" )
+    }
+}
+```
+
+[Delegation](delegate.md) example:
+```conf
+url.rewrite-once = (
+    "^/\.well-known/matrix/client$" => "/.well-known/matrix/client.json",
+    "^/\.well-known/matrix/server$" => "/.well-known/matrix/server.json"
+)
+
+# This condition intentionally matches the post-rewrite URLs.
+$HTTP["url"] =~ "^/\.well-known/matrix/(client|server)\.json$" {
+    mimetype.assign = ( ".json" => "application/json" )
+    setenv.set-response-header = ( "Access-Control-Allow-Origin" => "*" )
+}
+```
+
 
 ## Health check endpoint