From e417a908f2be291de0d39f8879dd8ca4e29b46c5 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Mon, 3 Aug 2026 07:54:32 -0700 Subject: [PATCH] Upgrade to AlmaLinux 10 and fix WebSocket proxying Base image moves from AlmaLinux 9 to 10, which forces two related changes: EPEL repo URL bumps to the el10 release RPM, and tini is replaced with dumb-init as PID 1 since tini is not packaged in EPEL 10. Both provide the signal forwarding and zombie reaping the wedged-container fix relies on. Nginx 1.26 in AlmaLinux 10 deprecates the `listen ... http2` parameter, so the server block now uses the separate `http2 on;` directive. Also fixes three issues that affected WebSocket apps (socket.io, ws): - `Connection: upgrade` was hardcoded on every proxied request, including ordinary HTTP. Now driven by a `map $http_upgrade $connection_upgrade` so only genuine upgrade requests carry it. - No explicit proxy read/send timeout meant idle WebSockets were cut at nginx's 60s default. Set to 600s, which clears any sane heartbeat without pinning connection slots (worker_connections is 512, two per client). - `large_client_header_buffers 2 1k` returned 400 for any single header line over 1KB, which session cookies and bearer tokens routinely exceed. Raised to the nginx default of 4 8k; buffers are allocated on demand, so this only costs memory for requests that need it. Verified by rendering the generated config and running it under nginx with a Node backend: WebSocket handshakes return 101 and reach the upstream 'upgrade' event, polling requests arrive with `Connection: close`, and a 3KB cookie returns 200 where the old buffer setting returned 400. README gains a WebSocket Support section covering the PM2 cluster-mode trap, the concurrency ceiling, and reconnects on memory restarts. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 2 ++ Dockerfile | 6 +++--- MEMORY-GUIDE.md | 2 +- README.md | 32 +++++++++++++++++++++++++++++++- configs/nginx.conf | 16 ++++++++++++++-- scripts/create-nginx-config.sh | 18 ++++++++++++++++-- scripts/entrypoint.sh | 9 +++++---- 7 files changed, 72 insertions(+), 13 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2b4cbea --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Claude Code local settings +.claude/ diff --git a/Dockerfile b/Dockerfile index 7dfeaaf..d1a141b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,11 +1,11 @@ -FROM almalinux/9-base +FROM almalinux/10-base ARG NODEVER=20 # Install repos, update, install only needed packages, clean up in one layer RUN dnf install -y \ - https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \ + https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm && \ dnf update -y && \ - dnf install -y wget procps cronie iproute nginx openssl git microdnf make gcc gcc-c++ tini && \ + dnf install -y wget procps cronie iproute nginx openssl git microdnf make gcc gcc-c++ dumb-init && \ dnf group install -y 'Development Tools' && \ dnf clean all && \ rm -rf /var/cache/dnf /usr/share/doc /usr/share/man /usr/share/locale/* \ diff --git a/MEMORY-GUIDE.md b/MEMORY-GUIDE.md index dc4df44..04b76d9 100644 --- a/MEMORY-GUIDE.md +++ b/MEMORY-GUIDE.md @@ -15,7 +15,7 @@ | Component | Memory Usage | Notes | |-----------|--------------|-------| -| **Base AlmaLinux 9** | ~80-120MB | Minimal base system | +| **Base AlmaLinux 10** | ~80-120MB | Minimal base system | | **Node.js Runtime** | ~30-50MB | V8 JavaScript engine | | **PM2 Process Manager** | ~15-25MB | Process monitoring and management | | **Nginx (Optimized)** | ~8-15MB | Single worker, limited buffers | diff --git a/README.md b/README.md index 62d2574..2cf0c03 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Cloud Node Container -This is a base container for running Node.js applications, supporting multiple Node.js versions (18, 20, 22). The default is Node.js 20. The container is based on AlmaLinux 9 and uses Nginx as a reverse proxy with SSL. It is designed for both development and production use. +This is a base container for running Node.js applications, supporting multiple Node.js versions (18, 20, 22). The default is Node.js 20. The container is based on AlmaLinux 10 and uses Nginx as a reverse proxy with SSL. It is designed for both development and production use. **You must have Docker or compatible containerization software running.** @@ -164,6 +164,35 @@ The container automatically generates an ecosystem.config.js file from your pack }); ``` +### WebSocket Support (socket.io, ws) + +WebSockets work out of the box — no configuration needed on your side. Nginx proxies +upgrade requests through to your app on port 3000, and the auto-generated PM2 config +runs a **single fork-mode process**, so socket.io's session affinity requirement is +satisfied automatically. A stock `io.attach(server)` / `new WebSocketServer({ server })` +setup just works over `wss://your-domain/`. + +Things to know before you scale up: + +- **Don't switch to PM2 cluster mode.** If you supply your own `ecosystem.config.js` + with `exec_mode: 'cluster'` and `instances` greater than 1, socket.io's HTTP + long-polling handshake will bounce between workers and clients will see + `Session ID unknown` errors. To run multiple instances you need both sticky + sessions and a shared adapter (`@socket.io/cluster-adapter` with + `@socket.io/sticky`) — the container does not set these up for you. +- **Concurrency ceiling is roughly 250 simultaneous connections.** Nginx runs one + worker with `worker_connections 512`, and each proxied client consumes two slots + (browser side plus upstream side). Fine for typical traffic; a limit to plan + around for a chat or presence-heavy app. +- **Keep your heartbeat under 600 seconds.** Nginx closes idle proxied connections + after 600s with no data. Socket.io's default `pingInterval` of 25s is well inside + this. Only relevant if you deliberately raise it. +- **Expect reconnects on memory restarts.** PM2 restarts the app at 256MB + (`max_memory_restart`), which drops every open socket. Socket.io clients + reconnect automatically, but connection state held only in process memory is + lost. WebSocket buffers add up — if you hold thousands of connections, watch for + restart loops in `logs/nodejs/`. + ### Step 3: Example Applications See the `examples/` directory for complete working examples: @@ -201,6 +230,7 @@ When you place your app in `user/app/`, the container automatically: - **Multiple Node.js Versions:** 18, 20, 22 (set with `NODEVER` environment variable) - **Process Management:** PM2 for production-grade Node.js application management - **Reverse Proxy:** Nginx handles SSL termination and proxies requests to Node.js +- **WebSockets:** socket.io and `ws` supported out of the box (see [WebSocket Support](#websocket-support-socketio-ws)) - **Automatic Backups:** Application files backed up every 30 minutes in DEV mode - **Log Management:** Log rotation compresses logs older than 3 days, deletes after 7 days - **Session Storage:** Memcached available in DEV mode for session management diff --git a/configs/nginx.conf b/configs/nginx.conf index 1fad60f..44cc0b1 100644 --- a/configs/nginx.conf +++ b/configs/nginx.conf @@ -15,8 +15,20 @@ http { client_body_buffer_size 16k; client_header_buffer_size 1k; client_max_body_size 8m; - large_client_header_buffers 2 1k; - + # Buffers are allocated on demand, so the larger size only costs memory for + # requests that actually need it. 1k rejected any single header line over + # 1KB with a 400 -- session cookies and Authorization bearer tokens + # routinely exceed that. + large_client_header_buffers 4 8k; + + # Maps the Connection header sent upstream to whether the client actually + # requested an upgrade. Used by conf.d/default.conf so WebSocket handshakes + # (socket.io, ws) upgrade while ordinary requests keep normal semantics. + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + # Real IP configuration for HAProxy set_real_ip_from 10.0.0.0/8; # Private network range set_real_ip_from 172.16.0.0/12; # Private network range diff --git a/scripts/create-nginx-config.sh b/scripts/create-nginx-config.sh index 8d4dd64..dac0d59 100755 --- a/scripts/create-nginx-config.sh +++ b/scripts/create-nginx-config.sh @@ -15,7 +15,8 @@ server { } server { - listen 443 ssl http2; + listen 443 ssl; + http2 on; server_name $domain $serveralias; ssl_certificate /etc/pki/tls/certs/localhost.crt; @@ -30,8 +31,21 @@ server { location / { proxy_pass http://nodejs_backend; proxy_http_version 1.1; + + # WebSocket support (socket.io, ws). \$connection_upgrade is defined by + # the map in /etc/nginx/nginx.conf: 'upgrade' when the client asked to + # upgrade, 'close' otherwise -- a hardcoded 'upgrade' would send the + # header on every ordinary request too. proxy_set_header Upgrade \$http_upgrade; - proxy_set_header Connection 'upgrade'; + proxy_set_header Connection \$connection_upgrade; + + # An idle WebSocket sends no bytes, and the default 60s read timeout + # would cut it. 600s clears any sane heartbeat (socket.io pings every + # 25s by default) without pinning connection slots for an hour -- + # worker_connections is 512 and each client uses two. + proxy_read_timeout 600s; + proxy_send_timeout 600s; + proxy_set_header Host \$host; proxy_set_header X-Real-IP \$remote_addr; proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for; diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh index 133c41f..37de07a 100755 --- a/scripts/entrypoint.sh +++ b/scripts/entrypoint.sh @@ -97,10 +97,11 @@ tail -F /home/$user/logs/nginx/access.log \ /home/$user/logs/nodejs/out.log \ /home/$user/logs/nodejs/error.log 2>/dev/null & -# Start PM2 under tini so it becomes PID 1 (with proper signal forwarding +# Start PM2 under dumb-init so it becomes PID 1 (with proper signal forwarding # and zombie reaping for nginx/crond/memcached children that reparent here). -# When pm2 exits (e.g. max_restarts exhausted), tini exits and Docker's +# When pm2 exits (e.g. max_restarts exhausted), dumb-init exits and Docker's # restart policy brings the container back. -echo "Starting PM2 as user $user (under tini as PID 1)..." +# (dumb-init replaces tini, which is not packaged in EPEL 10.) +echo "Starting PM2 as user $user (under dumb-init as PID 1)..." cd /home/$user/app -exec tini -- su - $user -c "cd /home/$user/app && NODE_ENV=production pm2 start ecosystem.config.js --no-daemon" \ No newline at end of file +exec dumb-init -- su - $user -c "cd /home/$user/app && NODE_ENV=production pm2 start ecosystem.config.js --no-daemon" \ No newline at end of file