Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(deploy): threaded gunicorn worker — gevent-websocket class broke WebSocket

Juan Denis751dde7a7db4
diff --git a/CLAUDE.md b/CLAUDE.md
index 1e4774e1..754045a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -54,7 +54,9 @@ Other backend components:
- `run.py` — Entry point
> **Agent gateway is single-worker.** All connected-agent state lives in-memory
-> in one process, so the panel must run a **single** gevent-websocket worker;
+> in one process, so the panel must run a **single** gunicorn worker process
+> (`-w 1 --threads N`, plain threaded worker — NOT the gevent-websocket worker
+> class, which double-answers the WS handshake against `async_mode='threading'`);
> multi-worker deployments silently misroute agent commands. See
> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [SECURITY.md](SECURITY.md).
diff --git a/Dockerfile b/Dockerfile
index 9e9deb8a..0a03a0ec 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -103,4 +103,7 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
WORKDIR /app/backend
# Default command - use gunicorn for production
-CMD ["sh", "-c", "exec gunicorn --worker-class geventwebsocket.gunicorn.workers.GeventWebSocketWorker --workers 1 --bind 0.0.0.0:${SERVERKIT_BACKEND_PORT:-5000} --timeout 120 --access-logfile - --error-logfile - run:app"]
+# Single process (agent gateway state is in-memory) + threads: the app runs
+# async_mode='threading' (simple-websocket serves WS); a gevent-websocket
+# worker would double-answer the upgrade handshake and break WebSocket.
+CMD ["sh", "-c", "exec gunicorn --workers 1 --threads 100 --bind 0.0.0.0:${SERVERKIT_BACKEND_PORT:-5000} --timeout 120 --access-logfile - --error-logfile - run:app"]
diff --git a/SECURITY.md b/SECURITY.md
index 1bbecb3b..d0788660 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -59,6 +59,7 @@ For a detailed internal audit of the panel, see
## Deployment Note
The agent gateway keeps all connected-agent state in-memory in a single process.
-Run the panel with a **single** gevent-websocket worker; multi-worker
+Run the panel with a **single** gunicorn worker process (threaded worker,
+`-w 1 --threads N` — not the gevent-websocket worker class); multi-worker
deployments can misroute agent commands. See
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
diff --git a/backend/requirements.txt b/backend/requirements.txt
index 00e8f198..2c909903 100644
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -22,8 +22,12 @@ python-engineio==4.11.2
# System monitoring
psutil==5.9.7
-# Production server
+# Production server. WebSocket is served by simple-websocket (engineio's
+# threading driver) under a plain threaded gunicorn worker — do NOT deploy
+# with the gevent-websocket worker class; it double-answers the WS handshake
+# against async_mode='threading' (browser: "Invalid frame header").
gunicorn==23.0.0
+simple-websocket==1.1.0
gevent==25.4.2
gevent-websocket==0.10.1
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index adc4b7cd..27237074 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -209,9 +209,12 @@ ServerKit follows a modern 3-tier architecture:
> **Deployment constraint — single WebSocket worker.** The agent gateway keeps
> all connected-agent state (the registry of live agents, socket↔server index,
> session tokens, and in-flight command queues) **in-memory in one process**.
-> Run the panel with a **single** gevent-websocket worker. Scaling to multiple
-> workers without a shared backplane (e.g. a Redis message queue) will silently
-> misroute or drop commands for agents connected to a different worker.
+> Run the panel with a **single** gunicorn worker process — a plain threaded
+> worker (`-w 1 --threads N`; WebSocket is served by simple-websocket to match
+> `async_mode='threading'` — the gevent-websocket worker class double-answers
+> the WS handshake and breaks WebSocket). Scaling to multiple workers without
+> a shared backplane (e.g. a Redis message queue) will silently misroute or
+> drop commands for agents connected to a different worker.
---
diff --git a/templates/serverkit-backend.service.in b/templates/serverkit-backend.service.in
index 2df26c14..4cd72115 100644
--- a/templates/serverkit-backend.service.in
+++ b/templates/serverkit-backend.service.in
@@ -12,7 +12,13 @@ Environment="PATH=@SERVERKIT_VENV_DIR@/bin:/usr/local/bin:/usr/bin:/bin"
Environment="FLASK_ENV=production"
Environment="SERVERKIT_INSTALL_DIR=@SERVERKIT_DIR@"
EnvironmentFile=@SERVERKIT_DIR@/.env
-ExecStart=@SERVERKIT_VENV_DIR@/bin/gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 -b 0.0.0.0:@PORT@ --timeout 120 --access-logfile @LOG_DIR@/access.log --error-logfile @LOG_DIR@/error.log run:app
+# Single PROCESS (-w 1) is mandatory: the agent gateway keeps connected-agent
+# state in memory. Threaded worker (not GeventWebSocketWorker): the app runs
+# async_mode='threading', where engineio serves WebSocket via simple-websocket
+# on the raw socket — a gevent-websocket worker ALSO answers the upgrade,
+# producing a double 101 handshake the browser reports as
+# "Invalid frame header" (WS then silently degrades to polling).
+ExecStart=@SERVERKIT_VENV_DIR@/bin/gunicorn -w 1 --threads 100 -b 0.0.0.0:@PORT@ --timeout 120 --access-logfile @LOG_DIR@/access.log --error-logfile @LOG_DIR@/error.log run:app
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5