Merge pull request 'Upgrade to AlmaLinux 10 and fix WebSocket proxying' (#2) from upgrade-almalinux-10 into main

.dockerignore

@@ -23,6 +23,7 @@ temp/
 # IDE files
 .vscode/
 .idea/
+.claude/
 *.swp
 *.swo
 

.gitignore

@@ -0,0 +1,2 @@
+# Claude Code local settings
+.claude/

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/* \

MEMORY-GUIDE.md

@@ -15,10 +15,10 @@
 
 | 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 |
+| **Nginx (Optimized)** | ~8-15MB | Single worker; header buffers allocated on demand |
 | **User Application** | ~50-200MB | Depends on application complexity |
 | **Memcached (DEV mode)** | ~10-15MB | 32MB memory limit, actual usage varies |
 | **System Overhead** | ~30-50MB | Logging, cron, system processes |
@@ -33,7 +33,11 @@
 2. **PM2 Memory Restart**: Applications restart at 256MB usage
 3. **Memcached Limit**: 32MB maximum cache size
 4. **Nginx Workers**: Single worker process for memory efficiency
-5. **Buffer Limits**: Reduced client buffer sizes
+5. **Buffer Limits**: Reduced client body buffer (16k) and 8MB max body size.
+   Header buffers use the nginx default (`large_client_header_buffers 4 8k`)
+   rather than a reduced value -- a smaller limit rejects ordinary session
+   cookies with a 400. These are allocated per request only when a request
+   actually needs them, not preallocated per connection.
 6. **Log Buffering**: 2-minute flush intervals to reduce I/O
 
 ### Application-Level Recommendations

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

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

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;

scripts/entrypoint.sh

@@ -97,10 +97,17 @@ 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.)
+#
+# --single-child is required for parity with tini. dumb-init defaults to
+# setsid() plus forwarding signals to the whole process group, whereas tini
+# without -g forwards only to its direct child. Without this flag a
+# `docker stop` would signal the tenant's node process directly and at the
+# same moment as pm2, bypassing pm2's kill_timeout shutdown sequencing.
+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"
+exec dumb-init --single-child -- su - $user -c "cd /home/$user/app && NODE_ENV=production pm2 start ecosystem.config.js --no-daemon"