From e0a997c22784b453735b24907e607412b153ba56 Mon Sep 17 00:00:00 2001 From: tototomate123 Date: Wed, 29 Oct 2025 10:57:23 +0100 Subject: [PATCH] docs(reverse-proxy): restructure and add nginx guide - Moved Caddy and Nginx configuration examples to separate files - Added documentation for Nginx setup - Updated generic reverse proxy section --- docs/SUMMARY.md | 2 + docs/deploying/generic.md | 67 ++++------- docs/deploying/reverse-proxy-caddy.md | 48 ++++++++ docs/deploying/reverse-proxy-nginx.md | 164 ++++++++++++++++++++++++++ 4 files changed, 237 insertions(+), 44 deletions(-) create mode 100644 docs/deploying/reverse-proxy-caddy.md create mode 100644 docs/deploying/reverse-proxy-nginx.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 02d6bff0..abc7dca0 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -5,6 +5,8 @@ - [Examples](configuration/examples.md) - [Deploying](deploying.md) - [Generic](deploying/generic.md) + - [Reverse Proxy - Caddy](deploying/reverse-proxy-caddy.md) + - [Reverse Proxy - Nginx](deploying/reverse-proxy-nginx.md) - [NixOS](deploying/nixos.md) - [Docker](deploying/docker.md) - [Kubernetes](deploying/kubernetes.md) diff --git a/docs/deploying/generic.md b/docs/deploying/generic.md index 24f94c7e..667085e8 100644 --- a/docs/deploying/generic.md +++ b/docs/deploying/generic.md @@ -141,46 +141,31 @@ sudo chmod 700 /var/lib/tuwunel/ ## Setting up the Reverse Proxy -We recommend Caddy as a reverse proxy, as it is trivial to use, handling TLS certificates, reverse proxy headers, etc transparently with proper defaults. -For other software, please refer to their respective documentation or online guides. +We recommend Caddy as a reverse proxy, as it is trivial to use, handling TLS certificates, reverse proxy headers, etc. transparently with proper defaults. However, Nginx is also well-supported and widely used. -### Caddy +**Choose your reverse proxy:** -After installing Caddy via your preferred method, create `/etc/caddy/conf.d/tuwunel_caddyfile` -and enter this (substitute for your server name). +- **[Caddy Setup Guide](reverse-proxy-caddy.md)** - Recommended for ease of use and automatic TLS +- **[Nginx Setup Guide](reverse-proxy-nginx.md)** - Popular choice with extensive documentation -```caddyfile -your.server.name, your.server.name:8448 { - # TCP reverse_proxy - reverse_proxy localhost:8008 - # UNIX socket - #reverse_proxy unix//run/tuwunel/tuwunel.sock -} -``` +### Quick Overview -That's it! Just start and enable the service and you're set. +Regardless of which reverse proxy you choose, you will need to: -```bash -sudo systemctl enable --now caddy -``` +1. **Reverse proxy the following routes:** + - `/_matrix/` - core Matrix C-S and S-S APIs + - `/_tuwunel/` - ad-hoc Tuwunel routes such as `/local_user_count` and `/server_version` -### Other Reverse Proxies +2. **Optionally reverse proxy (recommended):** + - `/.well-known/matrix/client` and `/.well-known/matrix/server` if using Tuwunel to perform delegation (see the `[global.well_known]` config section) + - `/.well-known/matrix/support` if using Tuwunel to send the homeserver admin contact and support page (formerly known as MSC1929) + - `/` if you would like to see `hewwo from tuwunel woof!` at the root -_Specific contributions for other proxies are welcome!_ +3. **Handle ports:** + - Port 443 (HTTPS) for client-server API + - Port 8448 for federation (if federating with other homeservers) -You will need to reverse proxy everything under following routes: -- `/_matrix/` - core Matrix C-S and S-S APIs -- `/_tuwunel/` - ad-hoc Tuwunel routes such as `/local_user_count` and -`/server_version` - -You can optionally reverse proxy the following individual routes: -- `/.well-known/matrix/client` and `/.well-known/matrix/server` if using -Tuwunel to perform delegation (see the `[global.well_known]` config section) -- `/.well-known/matrix/support` if using Tuwunel to send the homeserver admin -contact and support page (formerly known as MSC1929) -- `/` if you would like to see `hewwo from tuwunel woof!` at the root - -See the following spec pages for more details on these files: +See the following spec pages for more details on well-known files: - [`/.well-known/matrix/server`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixserver) - [`/.well-known/matrix/client`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient) - [`/.well-known/matrix/support`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixsupport) @@ -189,21 +174,15 @@ Examples of delegation: - - -For Apache and Nginx there are many examples available online. +### Other Reverse Proxies -Lighttpd is not supported as it seems to mess with the `X-Matrix` Authorization -header, making federation non-functional. If a workaround is found, feel free to share to get it added to the documentation here. +_Specific contributions for other proxies are welcome!_ -If using Apache, you need to use `nocanon` in your `ProxyPass` directive to prevent httpd from messing with the `X-Matrix` header (note that Apache isn't very good as a general reverse proxy and we discourage the usage of it if you can). +**Not Recommended:** +- **Apache**: While possible, Apache requires special configuration (`nocanon` in `ProxyPass`) to prevent corruption of the `X-Matrix` header. +- **Lighttpd**: Its proxy module alters the `X-Matrix` authorization header, breaking federation functionality. -If using Nginx, you need to give Tuwunel the request URI using `$request_uri`, or like so: -- `proxy_pass http://127.0.0.1:6167$request_uri;` -- `proxy_pass http://127.0.0.1:6167;` - -Nginx users need to increase `client_max_body_size` (default is 1M) to match -`max_request_size` defined in tuwunel.toml. - -## You're done +## You are done Now you can start Tuwunel with: diff --git a/docs/deploying/reverse-proxy-caddy.md b/docs/deploying/reverse-proxy-caddy.md new file mode 100644 index 00000000..dbee256d --- /dev/null +++ b/docs/deploying/reverse-proxy-caddy.md @@ -0,0 +1,48 @@ +# Reverse Proxy Setup - Caddy + +[<= Back to Generic Deployment Guide](generic.md#setting-up-the-reverse-proxy) + +We recommend Caddy as a reverse proxy, as it is trivial to use, handling TLS certificates, reverse proxy headers, etc. transparently with proper defaults. + +## Installation + +Install Caddy via your preferred method. Refer to the [official Caddy installation guide](https://caddyserver.com/docs/install) for your distribution. + +## Configuration + +After installing Caddy, create `/etc/caddy/conf.d/tuwunel_caddyfile` and enter this (substitute `your.server.name` with your actual server name): + +```caddyfile +your.server.name, your.server.name:8448 { + # TCP reverse_proxy + reverse_proxy localhost:8008 + # UNIX socket (alternative - comment out the line above and uncomment this) + #reverse_proxy unix//run/tuwunel/tuwunel.sock +} +``` + +### What this does + +- Handles both port 443 (HTTPS) and port 8448 (Matrix federation) automatically +- Automatically provisions and renews TLS certificates via Let's Encrypt +- Sets all necessary reverse proxy headers correctly +- Routes all traffic to Tuwunel listening on `localhost:8008` + +That's it! Just start and enable the service and you're set. + +```bash +sudo systemctl enable --now caddy +``` + +## Verification + +After starting Caddy, verify it's working by checking: + +```bash +curl https://your.server.name/_tuwunel/server_version +curl https://your.server.name:8448/_tuwunel/server_version +``` + +--- + +[=> Continue with "You're Done"](generic.md#you-are-done) diff --git a/docs/deploying/reverse-proxy-nginx.md b/docs/deploying/reverse-proxy-nginx.md new file mode 100644 index 00000000..53008e2b --- /dev/null +++ b/docs/deploying/reverse-proxy-nginx.md @@ -0,0 +1,164 @@ +# Reverse Proxy Setup - Nginx + +[<= Back to Generic Deployment Guide](generic.md#setting-up-the-reverse-proxy) + +This guide shows you how to configure Nginx as a reverse proxy for Tuwunel with TLS support. + +## Installation + +Install Nginx via your preferred method. Most distributions include Nginx in their package repositories: + +```bash +# Debian/Ubuntu +sudo apt install nginx + +# Red Hat/Fedora +sudo dnf install nginx + +# Arch Linux +sudo pacman -S nginx +``` + +## Configuration + +Create a new configuration file at `/etc/nginx/sites-available/tuwunel` (or `/etc/nginx/conf.d/tuwunel.conf` on some distributions): + +```nginx +# Client-Server API over HTTPS (port 443) +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name matrix.example.com; + + # Nginx standard body size is 1MB, which is quite small for media uploads + # Increase this to match the max_request_size in your tuwunel.toml + client_max_body_size 100M; + + # Forward requests to Tuwunel (listening on 127.0.0.1:8008) + location / { + proxy_pass http://127.0.0.1:8008; + + # Preserve host and scheme - critical for proper Matrix operation + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto https; + } + + # TLS configuration (Let's Encrypt example using certbot) + ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem; +} + +# Matrix Federation over HTTPS (port 8448) +# Only needed if you want to federate with other homeservers +# Don't forget to open port 8448 in your firewall! +server { + listen 8448 ssl http2; + listen [::]:8448 ssl http2; + server_name matrix.example.com; + + # Same body size increase for larger files + client_max_body_size 100M; + + # Forward to the same local port as client-server API + location / { + proxy_pass http://127.0.0.1:8008; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto https; + } + + # TLS configuration (same certificates as above) + ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem; +} +``` + +### Important Notes + +- **Replace `matrix.example.com`** with your actual server name +- **`client_max_body_size`**: Must match or exceed `max_request_size` in your `tuwunel.toml` +- **Do NOT use `$request_uri`** in `proxy_pass` - while some guides suggest this, it's not necessary for Tuwunel and can cause issues +- **IPv6**: The `listen [::]:443` and `listen [::]:8448` lines enable IPv6 support. Remove them if you don't need IPv6 + +### TLS Certificates + +The example above uses Let's Encrypt certificates via certbot. To obtain certificates: + +```bash +sudo certbot certonly --nginx -d matrix.example.com +``` + +Certbot will automatically handle renewal. Make sure to reload Nginx after certificate renewal: + +```bash +sudo systemctl reload nginx +``` + +### Optional: Timeout Configuration + +The default Nginx timeouts are usually sufficient for Matrix operations. Element's long-polling `/sync` requests typically run for 30 seconds, which is within Nginx's default timeouts. + +However, if you experience federation retries or dropped long-poll connections, you can extend the timeouts by adding these lines inside your `location /` blocks: + +```nginx +location / { + proxy_pass http://127.0.0.1:8008; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto https; + + # Optional: Extend timeouts if experiencing issues + proxy_read_timeout 300s; + proxy_send_timeout 300s; +} +``` + +## Enable the Configuration + +If using sites-available/sites-enabled structure: + +```bash +sudo ln -s /etc/nginx/sites-available/tuwunel /etc/nginx/sites-enabled/ +``` + +Test the configuration: + +```bash +sudo nginx -t +``` + +If the test passes, reload Nginx: + +```bash +sudo systemctl reload nginx +``` + +Enable Nginx to start on boot: + +```bash +sudo systemctl enable nginx +``` + +## Verification + +After configuring Nginx, verify it's working by checking: + +```bash +curl https://matrix.example.com/_tuwunel/server_version +curl https://matrix.example.com:8448/_tuwunel/server_version +``` + +## Troubleshooting + +### Apache Compatibility Note + +If you're considering Apache instead of Nginx: Apache is not well-suited as a reverse proxy for Matrix homeservers. If you must use Apache, you need to use `nocanon` in your `ProxyPass` directive to prevent httpd from corrupting the `X-Matrix` authorization header, which will break federation. + +### Lighttpd is Not Supported + +Lighttpd has known issues with the `X-Matrix` authorization header, making federation non-functional. We do not recommend using Lighttpd with Tuwunel. + +--- + +[=> Continue with "You're Done"](generic.md#you-are-done)