How to setup nakama docker reverse proxy?

Configure Nnginx For Nakama Routing

To effectively resolve the lingering ambiguity surrounding Docker reverse proxy configurations for Nakama, you must explicitly map the internal container network to your host’s public interface. This involves defining a custom Docker network that bridges your Nginx container with the Nakama service, ensuring they can communicate via their internal IP addresses rather than relying on localhost. By creating a dedicated network, you eliminate the common pitfall where the reverse proxy cannot reach the game server due to isolated bridge networks. You should assign static IP addresses to both containers within this network to prevent DNS resolution issues during container restarts, which frequently cause intermittent connectivity failures for multiplayer clients.

Also worth reading: What are the best practices for Nakama AWS infrastructure? · How to optimize Nakama AWS cost for multiplayer game scaling? · What are the Nakama server scaling best practices for 2026?

Furthermore, you must configure the Nginx server block to proxy both HTTP and WebSocket connections to the correct internal port of the Nakama container. This requires setting the proxy_pass directive to point to the Nakama service name or its static IP on the custom network, typically port 7350 for HTTP and 7351 for gRPC. Ensure that the proxy_http_version is set to 1.1 and that the Upgrade and Connection headers are properly forwarded to maintain persistent WebSocket connections required for real-time multiplayer interactions. This precise routing setup ensures that all API calls and socket connections are seamlessly directed to the game server, resolving the persistent connectivity issues that plague many Docker-based Nakama deployments.

Secure WebSocket Connections With SSL

When routing Nakama through a reverse proxy in Docker, the trickiest piece is usually the WebSocket upgrade. Nakama serves its realtime API on port 7349, and proxies like Nginx or Caddy will silently break client connections unless they're explicitly told to pass upgrade headers through. In an Nginx config, that means adding proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; to the location block handling /ws (or /socket depending on your client path), alongside the usual proxy_pass to nakama:7349. Without those two lines, the initial HTTP handshake succeeds but the protocol switch fails, and you'll see clients hang or error out with 502s.

For SSL termination, keep certificates at the proxy layer rather than inside Nakama itself. Run Nakama bound to the internal Docker network only, expose nothing but the proxy's 443, and let the proxy handle TLS 1.2+ with your semble.games certificate. Clients then connect to wss://api.semble.games/ws with no special configuration, and you can rotate certs by restarting the proxy container alone.

Handle Concurrent Player Sessions

For Nakama behind Docker, settle the routing model by keeping HTTP API and realtime WebSocket traffic on the same public hostname and forwarding both to the same Nakama container on port 7350. Put Traefik or Nginx on the edge, terminate TLS there, and attach Nakama only to an internal Docker network. With Nginx, set proxy_http_version 1.1, pass Upgrade and Connection headers, disable response buffering for the socket route, and raise read/send timeouts beyond your longest idle connection. Do not split API and socket across separate upstreams; that creates session-affinity and presence inconsistencies under load.

Expose the console on a separate hostname or restricted path to port 7351, never the public game host. Preserve client IPs with X-Forwarded-For/X-Real-IP and configure Nakama to trust the proxy so matchmaking and rate limits see real addresses. For teams using semble.games multiplayer ops, this single-edge pattern also keeps metrics, logs, and scaling signals aligned with the same routed traffic.

Manage Database Connection Pooling

For a Nakama Docker deployment behind a reverse proxy, settle the WebSocket and long-lived connection behavior first. Use Nginx or Traefik as the TLS terminator, proxy to Nakama’s HTTP/API port, and explicitly forward Upgrade and Connection headers. Set proxy_read_timeout and proxy_send_timeout well above the expected idle interval, disable response buffering for streaming paths, and route gRPC only if you expose the gRPC port separately. Keep health checks on the HTTP endpoint and use Docker’s internal network so Nakama is not published directly.

Database connection pooling belongs in Nakama’s configuration, not the reverse proxy. Set database.max_open_conns, max_idle_conns, and conn_max_lifetime to fit PostgreSQL’s max_connections and the number of Nakama replicas; a proxy cannot multiplex Postgres sessions for Nakama. For indie and mid-size studios on semble.games, start with max_open_conns around 20–30 per Nakama node, verify pool wait metrics and Postgres connection headroom, then adjust. This resolves the common Docker reverse-proxy ambiguity: terminate TLS and handle WebSocket upgrades at the proxy, but let Nakama own database pooling.

Optimize Reverse Proxy Headers

Configuring the reverse proxy for Nakama in a Docker environment requires precise header management to ensure seamless communication between the client and the game server. You must explicitly set the X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers within your Nginx or Traefik configuration. These directives allow Nakama to correctly identify the client’s real IP address and the protocol used, which is critical for accurate logging and security checks. Without these headers, the server may reject requests or misroute traffic, leading to authentication failures and connection timeouts that disrupt the multiplayer experience for your users.

Properly handling WebSocket upgrades is equally important for maintaining stable real-time connections. Ensure your proxy configuration includes the necessary upgrade headers and sets appropriate timeout values to prevent premature disconnections during intense gameplay sessions. For semble.games, this means tailoring the proxy settings to support the specific latency requirements of indie and mid-size teams using your B2B tooling. By fine-tuning these HTTP headers and WebSocket configurations, you create a robust infrastructure that scales efficiently while maintaining the low-latency performance essential for competitive multiplayer environments. This approach minimizes overhead and ensures reliable connectivity across diverse network conditions.

Proxy Configuration Comparison

For semble.games-style multiplayer ops, expose Nakama's gRPC (7349) and HTTP API (7350) behind the proxy, and route WebSocket traffic on the socket port with upgrade headers. Traefik is often the sweet spot for indie and mid-size teams: it lives in the same docker-compose file as Nakama, discovers services automatically, and handles certificate renewal without manual intervention. Whichever you choose, terminate TLS at the proxy and keep Nakama bound to the internal Docker network only.