diff --git a/.dockerignore b/.dockerignore index 638900e..fd1e897 100644 --- a/.dockerignore +++ b/.dockerignore @@ -23,6 +23,7 @@ temp/ # IDE files .vscode/ .idea/ +.claude/ *.swp *.swo 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..690e810 100644 --- a/MEMORY-GUIDE.md +++ b/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 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..109fbc7 100755 --- a/scripts/entrypoint.sh +++ b/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" \ No newline at end of file +exec dumb-init --single-child -- su - $user -c "cd /home/$user/app && NODE_ENV=production pm2 start ecosystem.config.js --no-daemon" \ No newline at end of file