Also posted here : https://community.nodebb.org/topic/19292/nodebb-scaling-clustering-redis-proxied-cloudflare-free-plan-integration-guide
Hello,
This guide covers a modern setup (2026+) running NodeBB in cluster mode with Redis behind nginx and Cloudflare’s free plan in proxied mode. The documentation here is over 10 years old and don’t account for cluster mode, Redis pub/sub, or how Cloudflare’s proxied mode interacts with socket.io session stickiness. This guide fills that gap.
Also, the official NodeBB nginx documentation will cause silent socket.io failures without the fixes described here.
– See here : https://community.nodebb.org/topic/19225/websocket-socket.io-403-xhr-poll-error-behind-cloudflare-cluster-scaling-redis/5
Prerequisites:
- NodeBB multi-process cluster with Redis pub/sub running, nginx configured as reverse proxy.
– See official documentation here : https://docs.nodebb.org/configuring/scaling/
- Cloudflare in proxied mode (orange cloud) pointing to your server IP.
- A valid SSL certificate installed on your server (covered in step 1 below)
Why the official NodeBB nginx doc breaks with Cloudflare
The official docs recommend ip_hash for session stickiness. This silently breaks behind Cloudflare because Cloudflare uses multiple outgoing IPs for the same end user. The socket.io polling request and the WebSocket upgrade can arrive from two different CF IPs, routing them to different cluster nodes. The second node has no session → 400 Bad Request.
Step 1 : SSL: Let’s Encrypt certificate + Cloudflare Full (Strict) mode
Why Full (Strict) and not just Full or Flexible?
Cloudflare offers four SSL modes:
| Mode |
Visitor → CF |
CF → your server |
Risk |
| Off |
HTTP |
HTTP |
Everything in plaintext |
| Flexible |
HTTPS |
HTTP |
CF to server is unencrypted — never use this |
| Full |
HTTPS |
HTTPS |
Accepts any cert, including self-signed — not validated |
| Full (Strict) |
HTTPS |
HTTPS |
Requires a valid, trusted cert — recommended |
Full (Strict) is the only mode that validates the certificate on your server. Without it, Cloudflare will happily connect to your server over HTTPS with an expired or self-signed cert, which provides no real security for the CF → origin leg.
Install Certbot and obtain a certificate
# Install Certbot with the nginx plugin
sudo apt install certbot python3-certbot-nginx -y
# Obtain a certificate for your domain
# (nginx must already be running and port 80 reachable from the internet)
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
Certbot will automatically edit your nginx vhost to add the SSL configuration and set up an HTTP → HTTPS redirect.
If Cloudflare is already in proxied mode (orange cloud), Certbot’s HTTP-01 challenge still works because Cloudflare forwards HTTP traffic to your server. No need to temporarily disable the proxy.
Verify auto-renewal
# Test the renewal process (dry run — no cert is actually renewed)
sudo certbot renew --dry-run
Certbot installs a systemd timer automatically. Certificates are renewed 30 days before expiry.
Configure Cloudflare SSL mode
In your Cloudflare dashboard, go to SSL/TLS → Overview and select Full (Strict).
Also enable these recommended options under SSL/TLS → Edge Certificates:
- Always Use HTTPS → On
- Minimum TLS Version → TLS 1.2
- Opportunistic Encryption → On
- TLS 1.3 → On
- Automatic HTTPS rewrites → On
Update your nginx vhost to listen on 443
After Certbot runs, your vhost should contain (Certbot adds this automatically):
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
# ... rest of your NodeBB proxy config
}
server {
listen 80;
server_name your-domain.com;
return 301 https://$host$request_uri;
}
With Cloudflare in proxied mode, the redirect from port 80 to 443 in nginx is technically handled by Cloudflare before it reaches your server (via the “Always Use HTTPS” rule above). Keep it in nginx anyway as a safety net for direct server access.
Step 2 : Nginx: trust Cloudflare’s real IP headers
By default nginx sees Cloudflare’s edge IPs, not your visitors’ IPs. You need to tell nginx which IP ranges to trust as a proxy, so $http_x_forwarded_for resolves correctly for the upstream hash in step 3.
Add this in you nodebb nginx virtualhost configuration :
# Cloudflare IPv4 ranges (update periodically from https://www.cloudflare.com/ips-v4)
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
# Cloudflare IPv6 ranges
set_real_ip_from 2400:cb00::/32;
set_real_ip_from 2606:4700::/32;
set_real_ip_from 2803:f800::/32;
set_real_ip_from 2405:b500::/32;
set_real_ip_from 2405:8100::/32;
set_real_ip_from 2a06:98c0::/29;
set_real_ip_from 2c0f:f248::/32;
real_ip_header CF-Connecting-IP;
Using CF-Connecting-IP instead of X-Forwarded-For is safer - Cloudflare guarantees this header contains exactly the real visitor IP with no spoofing risk.
Step 3 : Nginx: fix upstream session stickiness
The problem:
User → CF IP 1 → ip_hash → :4567 ✓ (session created)
User → CF IP 2 → ip_hash → :4568 ✗ (400 — no session!)
The fix:
User real IP → consistent hash → always :4567 ✓
In your NodeBB nginx vhost, update the upstream block like this :
upstream io_nodes {
# BEFORE (breaks with Cloudflare):
# ip_hash;
# AFTER — hash on the real visitor IP forwarded by Cloudflare
hash $http_x_forwarded_for consistent;
server 127.0.0.1:4567;
server 127.0.0.1:4568;
server 127.0.0.1:4569;
}
Make sure WebSocket proxying is present in your location /socket.io/ block:
location /socket.io/ {
proxy_pass http://io_nodes/socket.io/;
proxy_redirect off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
Step 4 : NodeBB config.json: origins & trust proxy
Two settings are required: tell NodeBB to trust the proxy headers, and restrict socket.io to your domain to prevent 403 origin errors.
{
"url": "https://your-domain.com",
"socket.io": {
"origins": "https://your-domain.com:*"
},
"trust proxy": true,
"secret": "...",
"database": "mongo",
"port": [4567, 4568, 4569],
"redis": { }
}
Without "trust proxy": true, NodeBB ignores X-Forwarded-Proto and may treat requests as HTTP even when the user is on HTTPS, causing CSRF and cookie issues behind Cloudflare.
Step 5 : Cloudflare: WAF rules (bypass socket.io & API)
Cloudflare’s WAF can interfere with socket.io's long-polling and your API endpoints. Create a WAF skip rule to bypass managed rules for these paths.
Go to Security → WAF → Custom rules and create a rule with this expression:
(http.request.uri.path contains "/socket.io")
or (http.request.uri.path contains "/api/")
Set the action to Skip → All remaining custom rules (and optionally also skip managed rulesets). Name it something like NodeBB - bypass socket.io and API.
On the free Cloudflare plan you get 5 custom WAF rules.
This single rule covers both socket.io and API.
Step 6 : Cloudflare: Cache rules (bypass socket.io)
Cloudflare must never cache socket.io traffic. Go to Caching → Cache Rules and create a rule with this expression:
(http.request.uri.path contains "/socket.io/")
or (http.request.uri.path contains "/api/")
Set the cache status to Bypass.
Optional: add a second cache rule to Cache Everything for /assets/ and /uploads/ paths to offload static files to Cloudflare’s CDN and reduce load on your server.
Step 7 : Reload & verify
# Test nginx config first
sudo nginx -t
# If OK, reload (zero downtime)
sudo systemctl reload nginx
# Restart NodeBB cluster
cd /path/to/nodebb
./nodebb restart
Open your forum in a browser, open DevTools → Network, filter by socket.io. You should see:
GET /socket.io/?transport=polling → 200
GET /socket.io/?transport=websocket → 101 Switching Protocols
All socket.io 400 errors should be gone. If you still see occasional 400s during a node restart, they are expected and transient - socket.io will reconnect automatically.
Summary checklist
| What |
Where |
| Scaling-Clustering Redis |
server |
| Let’s Encrypt certificate via Certbot |
server |
| SSL mode set to Full (Strict) |
Cloudflare dashboard |
| Always Use HTTPS + TLS 1.2 minimum |
Cloudflare dashboard |
| Nginx real IP from Cloudflare ranges |
/etc/nginx/conf.d/cloudflare-realip.conf |
Upstream: ip_hash → hash $http_x_forwarded_for consistent |
nginx vhost |
socket.io origins + trust proxy in config.json |
NodeBB |
WAF skip rule for /socket.io and /api/ |
Cloudflare dashboard |
Cache bypass rule for /socket.io and /api/ |
Cloudflare dashboard |
phenomlab
cagatay
