nginx-http3

Distribution switch notice

According to Debian Wiki, Debian bookworm has reach its end-of-life date in June 2026. Therefore, since version v9.0.0, the project will switch to Debian trixie as the packaging environment.

Table of Contents

• Features
• Usage
• Removed modules
• Add modules back
• Use in another distribution
• Recommended NGINX config

Features

• Based on latest NGINX mainline version
• HTTP/3 and QUIC support, powered by quictls
• Brotli support, powered by ngx_brotli
• GeoIP2 support, powered by ngx_http_geoip2_module
• Headers More support, powered by ngx_headers_more
• Remove mountains of useless modules to improve performance

Usage

Run following commands.

wget https://github.com/ononoki1/nginx-http3/releases/latest/download/nginx.deb
sudo apt install ./nginx.deb

Removed modules

• All modules that are not built by default, except http_ssl_module, http_v2_module and http_v3_module
• http_access_module
• http_autoindex_module
• http_browser_module
• http_charset_module
• http_empty_gif_module
• http_limit_conn_module
• http_memcached_module
• http_mirror_module
• http_referer_module
• http_split_clients_module
• http_scgi_module
• http_ssi_module
• http_upstream_hash_module
• http_upstream_ip_hash_module
• http_upstream_keepalive_module
• http_upstream_least_conn_module
• http_upstream_random_module
• http_upstream_zone_module

Add modules back

Fork this repo, enable GitHub Actions, edit build.sh and find the modules you want. Then remove related parameters and wait for GitHub Actions to run. After it finishes, you can download from releases.

For example, if you want to add http_scgi_module back, you need to remove --http-scgi-temp-path=/var/cache/nginx/scgi_temp and --without-http_scgi_module in build.sh.

Use in another distribution

Fork this repo, enable GitHub Actions, edit Dockerfile and build.sh, and change trixie to the one you like. Then wait for GitHub Actions to run. After it finishes, you can download from releases.

For example, if you want to use in Debian bookworm, you need to change trixie to bookworm.

Note: if you are using newer version of Debian (e.g. Debian testing or unstable), you can directly use this repo's pre-built releases because Debian is backward compatible.

Recommended NGINX config

http {
  brotli on;
  brotli_comp_level 6;
  gzip on;
  gzip_comp_level 6;
  http2 on;
  http3 on;
  ssl_certificate /path/to/cert_plus_intermediate;
  ssl_certificate_key /path/to/key;
  ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305; # change `ECDSA` to `RSA` if you use RSA certificate
  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_session_cache shared:TLS:10m;
  ssl_session_timeout 1d;
  ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
  server {
    listen 80 reuseport;
    listen [::]:80 reuseport; # delete if ipv6 is unavailable
    return 444;
  }
  server {
    listen 443 reuseport ssl;
    listen [::]:443 reuseport ssl;
    listen 443 reuseport quic;
    listen [::]:443 reuseport quic;
    ssl_reject_handshake on;
  }
  server {
    listen 80;
    listen [::]:80;
    server_name example.com dynamic.example.com php.example.com www.example.com;
    return 308 https://$host$request_uri;
  }
  server { # example for static site
    listen 443;
    listen [::]:443;
    listen 443 quic;
    listen [::]:443 quic;
    server_name example.com;
    root /path/to/static/site;
    add_header Alt-Svc 'h3=":443"; ma=2592000' always;
  }
  server { # example for dynamic site
    listen 443;
    listen [::]:443;
    listen 443 quic;
    listen [::]:443 quic;
    server_name dynamic.example.com;
    add_header Alt-Svc 'h3=":443"; ma=2592000' always;
    location / {
      proxy_pass http://ip:port;
    }
  }
  server { # example for dynamic site with php
    listen 443;
    listen [::]:443;
    listen 443 quic;
    listen [::]:443 quic;
    server_name php.example.com;
    root /path/to/php/site;
    index index.php;
    add_header Alt-Svc 'h3=":443"; ma=2592000' always;
    location ~ ^.+\.php$ {
      include fastcgi.conf;
      fastcgi_param HTTP_PROXY '';
      fastcgi_pass unix:/path/to/php/sock;
    }
  }
  server {
    listen 443;
    listen [::]:443;
    listen 443 quic;
    listen [::]:443 quic;
    server_name www.example.com;
    add_header Alt-Svc 'h3=":443"; ma=2592000' always;
    return 308 https://example.com$request_uri;
  }
}