From e906ada9216ec034594deff248434ce00a7380ce Mon Sep 17 00:00:00 2001
From: Lauri Ojansivu <x@xet7.org>
Date: Thu, 23 Jul 2026 10:40:56 +0300
Subject: [PATCH] Docs/Nginx: troubleshooting note for "wss ...
 /sockjs/.../websocket failed" (Connection upgrade header).

The example config is correct, but a common mistake is proxying WeKan with
`proxy_set_header Connection "";` (or omitting the `map $http_upgrade
$connection_upgrade` / `proxy_http_version 1.1`), which stops the SockJS WebSocket
upgrade and surfaces as `WebSocket connection to 'wss://HOST/sockjs/.../websocket'
failed`. Add a Troubleshooting section explaining the symptom and the exact three
lines (and the http-context map) needed on every proxy hop.

Thanks to akshat-goel and xet7 !

Fixes #6510,
---
 docs/Webserver/Nginx.md | 44 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/Webserver/Nginx.md b/docs/Webserver/Nginx.md
index c99d63c4d7..aed444d7bd 100644
--- a/docs/Webserver/Nginx.md
+++ b/docs/Webserver/Nginx.md
@@ -115,6 +115,50 @@ server {
 }
 ```
 
+### Troubleshooting: `WebSocket connection to 'wss://HOST/sockjs/.../websocket' failed`
+
+If the browser console shows `WebSocket connection to 'wss://HOST/sockjs/016/.../websocket'
+failed`, Nginx is not upgrading the connection to a WebSocket, so WeKan falls back to slow
+long-polling (or the realtime connection keeps dropping). This is almost always a missing or
+wrong `Connection` header — the two lines that hand the WebSocket `Upgrade` through the proxy:
+
+```
+proxy_http_version 1.1;
+proxy_set_header Upgrade    $http_upgrade;
+proxy_set_header Connection $connection_upgrade;
+```
+
+Checklist:
+
+- The `map $http_upgrade $connection_upgrade { default upgrade; '' close; }` block MUST be present
+  in the `http { }` context (in `nginx.conf` or an included file), because a `map` cannot live
+  inside a `server`/`location` block. Defining it but never using it does nothing.
+- In the `location` that proxies to WeKan, use **`proxy_set_header Connection $connection_upgrade;`**
+  — NOT `proxy_set_header Connection "";` and NOT `Connection "upgrade"` hard-coded. A hard-coded
+  empty or `keep-alive` value stops the upgrade for the SockJS `/sockjs/.../websocket` request. The
+  `$connection_upgrade` map sends `upgrade` for a WebSocket request and `close` otherwise, which is
+  what SockJS needs.
+- `proxy_http_version 1.1;` is required (WebSockets need HTTP/1.1); the default 1.0 cannot upgrade.
+- If WeKan is behind more than one proxy/load balancer, EACH hop needs these three lines.
+
+A minimal correct `location` (see the full example above):
+
+```
+map $http_upgrade $connection_upgrade { default upgrade; '' close; }   # in http { } context
+
+server {
+    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;   # NOT "" and NOT hard-coded
+        proxy_set_header Host       $host;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
 ### /etc/nginx/nginx.conf
 
 ```