Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Reverse Proxy Setup - Nginx

<= Back to Generic Deployment Guide

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:

# 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):

upstream tuwunel {
  server 127.0.0.1:8008; # IP and port where tuwunel is listening
}

server {
  # Client-Server API over HTTPS (port 443)
  listen 443 ssl;
  listen [::]:443 ssl;
  # 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!
  listen 8448 ssl;
  listen [::]:8448 ssl;
  http2 on;
  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
  location / {
    proxy_pass http://tuwunel;

    # Client address for `ip_source`; replaces any value the client sent
    proxy_set_header X-Forwarded-For $remote_addr;
    # Passes the public hostname. Tuwunel does not currently need this.
    proxy_set_header Host $host;
  }

  # 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;
}

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

If Nginx is the only way clients can reach Tuwunel, set ip_source = "rightmost_x_forwarded_for" under [global.http] in your tuwunel.toml. This tells Tuwunel to use the trusted X-Forwarded-For value as the client’s IP address.

Important

Restart Tuwunel after changing ip_source. A configuration reload that changes this setting is rejected.

The client setting under [global.well_known] in your tuwunel.toml holds your public HTTPS URL. Tuwunel uses this well_known.client setting to build public URLs for clients. The Host header and the request scheme do not supply those URLs.

TLS Certificates

The example above uses Let’s Encrypt certificates via certbot. To obtain certificates:

sudo certbot certonly --nginx -d matrix.example.com

Certbot will automatically handle renewal. Make sure to reload Nginx after certificate renewal:

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:

location / {
  proxy_pass http://tuwunel;
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header Host $host;

  # Optional: Extend timeouts if experiencing issues
  proxy_read_timeout 300s;
  proxy_send_timeout 300s;
}

Enable the Configuration

If using sites-available/sites-enabled structure:

sudo ln -s /etc/nginx/sites-available/tuwunel /etc/nginx/sites-enabled/

Test the configuration:

sudo nginx -t

If the test passes, reload Nginx:

sudo systemctl reload nginx

Enable Nginx to start on boot:

sudo systemctl enable nginx

Verification

After configuring Nginx, verify it’s working by checking:

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”