How to Set Up Mastodon Instance Behind Nginx With HTTP/3

Running a Mastodon instance requires a reliable web server to handle client connections and proxy requests to the Mastodon application server. Nginx is the most common reverse proxy for Mastodon, and enabling HTTP/3 on it brings faster connection establishment and better performance on unreliable networks. HTTP/3 uses the QUIC transport protocol instead of TCP, reducing latency for users worldwide. This guide explains how to configure Nginx to serve a Mastodon instance with HTTP/3 support.

Understanding HTTP/3 and Its Prerequisites for Mastodon

HTTP/3 is the third major version of the Hypertext Transfer Protocol. It replaces TCP with QUIC, a transport protocol built on UDP. For Mastodon, this means users see faster page loads, especially on mobile networks or connections with high packet loss. The Mastodon application itself does not need changes; the improvement happens entirely at the reverse proxy level.

Before enabling HTTP/3, confirm that your system meets these requirements:

Nginx Version

HTTP/3 support was added in Nginx 1.25.0. Run nginx -v to check your version. If you are on an older release, add the official Nginx repository or compile Nginx from source with the --with-http_v3_module flag. Many Linux distributions now package Nginx with HTTP/3 enabled by default.

OpenSSL Version

QUIC relies on TLS 1.3. OpenSSL 1.1.1 or later supports TLS 1.3, but for best compatibility use OpenSSL 3.x. Verify with openssl version. If your system has an older OpenSSL, you may need to compile Nginx against a newer OpenSSL build.

Firewall and Network Configuration

HTTP/3 uses UDP on port 443. Most server firewalls default to allowing only TCP. Open UDP 443 in iptables, ufw, or your cloud provider security group. If you use a CDN like Cloudflare, HTTP/3 is handled by the CDN edge and does not require server-side changes.

Steps to Configure Nginx for HTTP/3 on a Mastodon Instance

These instructions assume you have a working Mastodon instance behind Nginx. The configuration file is typically located at /etc/nginx/sites-available/mastodon or inside /etc/nginx/conf.d/.

1. Back up the current Nginx configuration
   Copy the existing Mastodon site configuration: sudo cp /etc/nginx/sites-available/mastodon /etc/nginx/sites-available/mastodon.backup. This allows you to revert if something goes wrong.
2. Edit the server block for port 443
   Open the Mastodon configuration file with a text editor: sudo nano /etc/nginx/sites-available/mastodon. Locate the server block that listens on port 443.
3. Add the HTTP/3 listen directive
   Inside that server block, add the line: listen 443 quic reuseport;. Place it immediately after the existing listen 443 ssl line. The reuseport parameter allows multiple worker processes to accept QUIC connections on the same port.
4. Add the Alt-Svc header
   Inside the same server block, add: add_header Alt-Svc 'h3=":443"; ma=86400';. This header tells browsers that HTTP/3 is available on port 443. The ma=86400 value sets the cache lifetime to 24 hours.
5. Enable TLS 1.3 in the ssl_protocols directive
   Ensure your configuration includes ssl_protocols TLSv1.2 TLSv1.3;. HTTP/3 requires TLS 1.3, but keeping TLS 1.2 ensures backward compatibility with older clients.
6. Verify SSL certificate and key paths
   Confirm that the ssl_certificate and ssl_certificate_key directives point to valid files. HTTP/3 will not work without a proper TLS certificate.
7. Test the Nginx configuration
   Run sudo nginx -t to check for syntax errors. If the test fails, review the error message and fix the reported issue.
8. Reload Nginx
   Apply the changes without dropping active connections: sudo systemctl reload nginx.
9. Open UDP port 443 in the firewall
   If you use ufw, run sudo ufw allow 443/udp. For iptables, add a rule: sudo iptables -A INPUT -p udp --dport 443 -j ACCEPT. Save the rule so it persists across reboots.
10. Verify HTTP/3 is working
    Use an online HTTP/3 test tool such as https://http3check.net or the curl command with the --http3 flag: curl --http3 -I https://mastodon.example.com. If the response includes the Alt-Svc header, HTTP/3 is active.

Common Issues When Enabling HTTP/3 on Mastodon

Nginx Fails to Start After Adding the quic Directive

If nginx -t reports an unknown directive error, your Nginx binary was compiled without the HTTP/3 module. Reinstall Nginx from a repository that includes HTTP/3 support, or compile Nginx with the --with-http_v3_module flag. On Ubuntu 22.04 and later, the default Nginx package from the official repository includes this module.

Browsers Do Not Switch to HTTP/3

The Alt-Svc header must be sent on the first HTTP/2 response. If the header is missing, browsers will not attempt a QUIC connection. Check your configuration with curl -I https://mastodon.example.com and look for the alt-svc line. If it is absent, verify that the add_header directive is inside the correct server block and not inside a location block.

UDP Traffic Blocked by Cloud Provider

Some cloud providers block UDP traffic by default or require an explicit security group rule. AWS, Google Cloud, and Azure all have separate settings for UDP. Add a custom rule for UDP port 443 in your cloud console. Without this, QUIC packets never reach Nginx.

HTTP/2 vs HTTP/3 for Mastodon: Key Differences

Item	HTTP/2	HTTP/3
Transport protocol	TCP	QUIC (UDP)
Connection establishment	Requires TCP and TLS handshake (2-3 round trips)	Combines handshake into 1 round trip (0-RTT possible)
Multiplexing	Single TCP connection; head-of-line blocking possible	Streams are independent; no head-of-line blocking
Nginx configuration change	No extra directives needed beyond SSL	Requires listen quic reuseport and Alt-Svc header
Firewall requirement	TCP 443 only	TCP 443 and UDP 443
Browser support	All modern browsers	Chrome, Firefox, Edge, Safari 14+

HTTP/3 offers measurable improvements for Mastodon users on mobile or congested networks. The configuration is minimal and does not affect the Mastodon application code. After enabling HTTP/3, monitor your Nginx access logs for QUIC-related entries and check that your server handles both HTTP/2 and HTTP/3 traffic smoothly. You can also fine-tune QUIC parameters such as quic_retry and quic_gso in the Nginx configuration for advanced performance tuning.