From 24ab9938039829c170bf7f9863d8057caeccd39e Mon Sep 17 00:00:00 2001
From: Andrew Cooks <acooks@gmail.com>
Date: Fri, 19 Jun 2026 15:27:19 +1000
Subject: [PATCH] docs(deploy): add nginx TLS reverse-proxy example

Add a ready-to-edit nginx config that terminates TLS and reverse-proxies
to jt-server, including the websocket Upgrade handling, plus a
"Running behind an HTTPS reverse proxy" section in the deployment guide.

Pairs with the wss:// client fix so JitterTrap can be served over HTTPS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 deploy/README.md                     | 33 ++++++++++++++++++++
 deploy/jittertrap-nginx.conf.example | 45 ++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 deploy/jittertrap-nginx.conf.example

diff --git a/deploy/README.md b/deploy/README.md
index cc3a82b..a483cb6 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -157,3 +157,36 @@ To use port 80:
 2. Change `-p 8080` to `-p 80` in `ExecStart`
 
 Or use a reverse proxy (nginx, Apache) to forward from port 80.
+
+## Running behind an HTTPS reverse proxy
+
+`jt-server` serves the HTML5 client **and** the websocket on a single HTTP
+port. To expose it over HTTPS, terminate TLS in a reverse proxy and forward
+both the HTTP requests and the websocket upgrade to `jt-server`.
+
+A ready-to-edit nginx example is provided in
+[`jittertrap-nginx.conf.example`](jittertrap-nginx.conf.example):
+
+```bash
+sudo cp deploy/jittertrap-nginx.conf.example /etc/nginx/conf.d/jittertrap.conf
+sudo $EDITOR /etc/nginx/conf.d/jittertrap.conf      # set your server_name
+sudo certbot --nginx -d jittertrap.example.com      # obtain a cert + 80->443 redirect
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+The essential detail is proxying the websocket `Upgrade`:
+
+```nginx
+map $http_upgrade $connection_upgrade { default upgrade; '' close; }
+# ...
+location / {
+    proxy_pass         http://127.0.0.1:8080;
+    proxy_http_version 1.1;
+    proxy_set_header   Upgrade    $http_upgrade;
+    proxy_set_header   Connection $connection_upgrade;
+    # ...
+}
+```
+
+The client selects `wss://` automatically when the page is served over HTTPS,
+so no client configuration is needed.
diff --git a/deploy/jittertrap-nginx.conf.example b/deploy/jittertrap-nginx.conf.example
new file mode 100644
index 0000000..faef61f
--- /dev/null
+++ b/deploy/jittertrap-nginx.conf.example
@@ -0,0 +1,45 @@
+# Example nginx reverse-proxy for serving JitterTrap over HTTPS.
+#
+# jt-server serves the HTML5 client AND the websocket on a single HTTP
+# port (8080 below). nginx terminates TLS and proxies both the HTTP
+# requests and the websocket Upgrade to jt-server.
+#
+# Usage:
+#   sudo cp deploy/jittertrap-nginx.conf.example /etc/nginx/conf.d/jittertrap.conf
+#   # set server_name below, then obtain a cert (also adds the 80->443 redirect):
+#   sudo certbot --nginx -d jittertrap.example.com
+#   sudo nginx -t && sudo systemctl reload nginx
+
+# Translate the websocket Upgrade header so connections are proxied
+# correctly. Must live in the http context (i.e. a conf.d/ file).
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen      80;
+    listen      [::]:80;
+    server_name jittertrap.example.com;          # <-- change me
+
+    # `certbot --nginx` adds the TLS listener + a 301 to https here.
+    # Without certbot, redirect manually instead:
+    #   return 301 https://$host$request_uri;
+
+    location / {
+        proxy_pass         http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+
+        # Websocket upgrade
+        proxy_set_header   Upgrade    $http_upgrade;
+        proxy_set_header   Connection $connection_upgrade;
+
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+
+        # Keep long-lived websocket connections open.
+        proxy_read_timeout 86400;
+    }
+}