Document lighttpd configuration example from matrix.jaxlug.ngo

[wltjr]

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!

Pull Request Checklist

• [ x] Pull request is based on the develop branch
• [x ] Pull request includes a changelog file. The entry should:
  • Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
  • Use markdown where necessary, mostly for code blocks.
  • End with either a period (.) or an exclamation mark (!).
  • Start with a capital letter.
  • Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
• [ x] Code style is correct (run the linters)

Please advise on the changelog aspect, I am unsure that is necessary for a documentation addition, same with code style, and any other modifications necessary for acceptance/merge.

Thank you!

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds a documented reverse-proxy configuration example for lighttpd to Synapse’s reverse-proxy documentation, expanding the set of supported/illustrated proxy options.

Changes:

• Adds lighttpd to the list of recommended reverse proxies.
• Introduces a new “### lighttpd” section with an example configuration, including UNIX-socket proxying and .well-known handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[anoadragon453]

Please advise on the changelog aspect, I am unsure that is necessary for a documentation addition

Yes, we request a changelog entry for all changes. This is so sysadmins updating to the new version of Synapse are aware that documentation for lighttpd is now available! 😁

same with code style, and any other modifications necessary for acceptance/merge.

In general yes, though in practice the linting won't fail documentation PRs unless you update the configuration documentation, which generates a jsonschema document off the back of the markdown.

Otherwise this looks good! Thanks for taking the time to contribute upstream! ✨

[anoadragon453]

Suggested change

	[HAProxy](https://www.haproxy.org/)
	[HAProxy](https://www.haproxy.org/),

[wltjr]

Corrected

[anoadragon453]

I think it would make sense to separate this out (as it's not required) into a "Delegation example" section, similar to how it's been done in the nginx, HAProxy and other HTTP server configs.

[wltjr]

Separated

[anoadragon453]

This looks fine (as someone who is only skimming the lighttpd docs).

I would just pop a ^ on the beginning and $ on the end of the path regexes, so you don't rewrite /.well-known/matrix/client/... requests. (edit: looks like copilot's suggestion above does this already.)

You could also avoid duplication on the headers with:

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" => "*"
    )
}

[wltjr]

Duplication avoided, thanks!

[anoadragon453]

If this is intended as "you can use IPv6 if you want!" comment, could you add a line saying so? Otherwise it comes across as dead code/accidentally left in.

[wltjr]

I added comment, you want to ensure that is commented out.

[wltjr]

Changelog added, just duplicated text from commit message, I can reword or modify as necessary. Other changes made as requested.

# serve json files as urls. is there a better way?

I removed this line but we may want to include something. I am unsure if there is a way for lighttpd to serve up the json data without having to do a URL file redirect, my gut says there maybe, but maybe not; like how nginx handles that. In lieu of such, my crude URL rewrite to json file works and maybe that is better for people who want stand alone files and not have it in some server config.

Let me know if there is anything else, thank you!

[wltjr]

I went ahead and added in changes for the /_synapse/admin URL path which is necessary for admin functions, and I also added a section on securing access to that. I should be done now. I assume squash/merge or other thus force push vs additional commits, if that matters. Cheers!