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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
fix(deploy): threaded gunicorn worker — gevent-websocket class broke WebSocket
Juan Denis751dde7a7db4
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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/Dockerfileindex 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.mdindex 1bbecb3b..d0788660 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -59,6 +59,7 @@ For a detailed internal audit of the panel, see## Deployment NoteThe 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-workerdeployments can misroute agent commands. See[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).diff --git a/backend/requirements.txt b/backend/requirements.txtindex 00e8f198..2c909903 100644--- a/backend/requirements.txt+++ b/backend/requirements.txt@@ -22,8 +22,12 @@ python-engineio==4.11.2# System monitoringpsutil==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.0gevent==25.4.2gevent-websocket==0.10.1diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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.inindex 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:appExecReload=/bin/kill -HUP $MAINPIDRestart=alwaysRestartSec=5