Node.js configuration for WoWonder real-time performance

Adding the WoWonder Node.js service can improve real-time delivery, but it is not a universal website speed switch. Database queries, PHP response time, media size, third-party scripts, and hosting limits remain separate performance concerns.

Define the real-time responsibility

Identify which events use the Node.js path and how the PHP application authenticates or publishes them. Verify the configured host, port, protocol, and application keys without exposing secrets in logs or public diagnostics.

Map the request and event paths

Draw the browser, public proxy, Node.js service, PHP application, database or broker, and recipient browser. Note which connection is HTTP, WebSocket or another transport; where TLS terminates; and how a logged-in WoWonder user is authorized. This prevents a “connected” socket from being mistaken for an authorized real-time session.

Confirm the installed WoWonder version's documented Node.js integration before applying advice from another release. Configuration field names, event contracts and deployment expectations can change. Keep a backup of modified files and compare local customizations so an upgrade does not silently remove required hooks.

Prepare the server path

Use a VPS or environment that permits the required process and port. Run the service under a process manager, set a controlled working directory and environment, and configure the Apache or Nginx reverse proxy and WebSocket upgrade headers. TLS must be valid end to end.

Proxy WebSockets on a narrow route

Send only the documented real-time endpoint to the Node.js upstream. Preserve the required host and forwarding information, allow the HTTP upgrade, and set timeouts suitable for long-lived connections. A broad proxy rule can accidentally bypass PHP routes or expose a service endpoint that was intended to remain internal.

When the public site uses HTTPS, the browser should connect through a secure endpoint. Avoid mixed content and validate the certificate on the public hostname. If TLS terminates at the proxy, protect the proxy-to-service network and configure the application to trust forwarded headers only from that proxy.

Protect authentication and origins

A WebSocket handshake can include cookies, so validate the allowed Origin and authenticate the session according to the platform's supported method. Do not accept an arbitrary user ID supplied by the browser. Authorize each channel, room or recipient action on the server; a valid connection is not permission to subscribe to all events.

Keep application keys and private endpoints in server environment configuration. Public browser bundles cannot safely contain a secret. Rotate credentials with a documented overlap strategy and restart or reload workers in a way that does not leave half the instances on an incompatible key.

Run it as an operable service

Use a dedicated unprivileged account, a fixed supported Node.js version and a lockfile-based install. The process manager should start the intended script from the intended directory, set a restart policy with backoff, capture structured logs and start after its network dependencies. Do not run a development watcher in production.

Define health and readiness separately. A process can be alive while disconnected from a broker or unable to accept new events. Monitor process restarts, memory, event-loop delay, active connections, authentication failures, message rate and delivery errors. Rotate logs before they fill the disk.

Test failure and recovery

Restart the Node.js process, rotate a deployment, interrupt a connection, and confirm the browser reconnects without duplicating handlers. Monitor memory, uncaught errors, connection counts, proxy errors, and application logs.

Bound reconnection behavior

Clients should retry with increasing delay and jitter rather than reconnecting every few milliseconds. After reconnecting, the application may need to resubscribe or refresh authoritative state because events during the gap can be missed. Give event handlers stable ownership so each navigation or reconnect does not attach another duplicate listener.

Real-time events should usually tell the interface that something changed, while the PHP/database API remains the source of truth. That design makes recovery simpler: after a disconnect, fetch the current conversation or notification state rather than trying to replay an unbounded stream of UI mutations.

Scale only after measuring one instance

Multiple Node.js instances need a shared event distribution strategy if a message accepted by one instance must reach a user connected to another. Sticky load balancing alone does not distribute published events. Use the integration's supported broker or adapter and test duplicate, delayed and out-of-order delivery.

Set connection and message-size limits before load testing. Measure memory per connection, event-loop delay and proxy capacity with representative authenticated traffic. A synthetic connection that sends no messages does not represent a busy chat or notification workload.

Measure the correct outcome

Compare event latency and reliability before and after the change. If normal page loads remain slow, profile PHP, MySQL, assets, and network delivery independently instead of attributing every delay to the real-time service.

Acceptance checklist

• The browser establishes one authenticated secure connection on desktop and mobile.
• Unauthorized origins, users and channel requests are rejected.
• Messages reach the intended recipient once at the application level.
• A service restart causes bounded reconnect and authoritative state recovery.
• Proxy and application logs share enough identifiers to trace a connection without exposing secrets.
• The PHP application remains usable when the real-time service is unavailable.
• Page performance is measured separately from event-delivery latency.

The Node.js service is successful when it provides a reliable, observable real-time path with a graceful fallback. It should reduce event delay without becoming a hidden single point of failure or a substitute for profiling the rest of the WoWonder stack.

Store a short deployment runbook with the installed versions, public route, internal port, process name, health check and rollback command, while keeping all secrets in the environment. That makes routine maintenance repeatable and prevents future troubleshooting from depending on shell history or memory.