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) <noreply@anthropic.com>

.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,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 |

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,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"
+exec dumb-init -- su - $user -c "cd /home/$user/app && NODE_ENV=production pm2 start ecosystem.config.js --no-daemon"