Why is there always an upstream block, even for one backend?

An upstream block gives Nginx a named pool to load-balance across, and it costs nothing to define even with a single server. Adding more backends later is then a one-line change to the upstream block instead of restructuring the whole server block.

Why does the WebSocket toggle add a separate map block?

Nginx needs to translate the client's Upgrade header into the correct Connection header value: 'upgrade' when a WebSocket upgrade is requested, and 'close' otherwise. The `map $http_upgrade $connection_upgrade` block is the standard way to compute that value once and reuse it in `proxy_set_header Connection $connection_upgrade`.

Can I use gRPC and WebSocket/caching together?

No, this generator treats gRPC as a distinct proxy mode: it swaps `proxy_pass` for `grpc_pass` and requires HTTP/2 on the listen directive, so the WebSocket and caching proxy_* directives (which apply to plain HTTP proxying) don't apply and are omitted when gRPC is enabled.

Is the generated caching setup production-ready as-is?

It's a reasonable starting point (a 10MB keys zone, 1GB max size, 60-minute inactive timeout) but review the cache key, cache-bypass rules for authenticated routes, and the `/var/cache/nginx/proxy_cache` directory's permissions before relying on it in production.

Nginx Reverse Proxy Config Generator - WebSocket, gRPC, Caching

Overview

Introduction

A reverse proxy config that just works for the common case, one backend, plain HTTP, no caching, is a few lines; the moment you add multiple backends, a WebSocket-based app, gRPC, or caching, the directive list grows and small omissions (a missing Upgrade header, a wrong http2 listen flag) cause silent failures.

This tool generates a complete Nginx server block with an upstream pool and optional WebSocket, gRPC, and caching support, so those directives are always paired correctly.

What Is Nginx Reverse Proxy Generator?

A generator for an Nginx server block that proxies to a named upstream block containing one or more backend servers, the standard shape for load-balanced reverse proxying in Nginx.

It supports three independent toggles: WebSocket upgrade support (a map block plus Upgrade/Connection headers), gRPC passthrough (grpc_pass with an HTTP/2 listener), and basic response caching (a proxy_cache_path plus per-location cache directives).

How Nginx Reverse Proxy Generator Works

You provide a server_name and one or more backend addresses, which become an `upstream backend_pool { server ...; }` block. You then toggle WebSocket, gRPC, and caching support.

The generator validates the server name and backend address formats, then assembles the server block: gRPC mode swaps proxy_pass for grpc_pass and forces an http2 listener; otherwise it emits proxy_pass plus the standard X-Forwarded-* headers, adding the WebSocket map/headers and cache directives as toggled.

When To Use Nginx Reverse Proxy Generator

Use it when putting Nginx in front of one or more application servers (Node.js, Python, Go, etc.) and you need load balancing across replicas.

Turn on the WebSocket toggle for apps using Socket.IO, native WebSockets, or similar; turn on gRPC for a gRPC backend; turn on caching for read-heavy, cacheable responses.

Often used alongside Load Balancer Config Generator, Rate Limiting Config Generator and Let's Encrypt Config Generator.

Features

Advantages

Always defines an upstream pool, so scaling from one backend to several later is a one-line addition instead of a config rewrite.
Pairs the WebSocket map block with the exact header directives it requires, a detail that's easy to get half-right by hand.
Keeps gRPC as a distinct, correctly-configured mode instead of silently mixing it with incompatible plain-HTTP proxy directives.

Limitations

Generates one server block for one virtual host; multiple domains or path-based routing to different upstreams need additional server/location blocks.
The generated caching setup uses conservative defaults and doesn't include cache-bypass logic for cookies/auth headers, review it for routes that must never be cached.

Examples

Two-backend pool with WebSocket support

Input

serverName: app.example.com, upstreamServers: [10.0.0.1:3000, 10.0.0.2:3000], websocketEnabled: true, grpcEnabled: false, cachingEnabled: false

Output

upstream backend_pool {
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend_pool;
        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;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Nginx round-robins requests across both upstream servers by default; the map block and Upgrade/Connection headers only appear because WebSocket support is enabled.

Best Practices & Notes

Best Practices

List backend servers by IP or internal DNS name that's stable inside your network, not by a public hostname that itself resolves back through this same proxy.
Pair this config with TLS termination (either on this same server block via ssl_certificate directives, or upstream of it) rather than serving production traffic over plain HTTP.
When enabling caching, add explicit `proxy_cache_bypass`/`proxy_no_cache` rules for any route that returns per-user or authenticated content.

Developer Notes

WebSocket support relies on Nginx's `map` directive computing `$connection_upgrade` from `$http_upgrade`, a well-documented pattern from the official Nginx WebSocket proxying guide, combined with `proxy_http_version 1.1` (required since HTTP/1.0 doesn't support Upgrade). gRPC support uses the `ngx_http_grpc_module`'s `grpc_pass` directive, which requires the listening socket to negotiate HTTP/2, hence forcing `listen 443 ssl http2` (or `listen ... http2` without TLS in trusted internal networks) whenever gRPC is enabled.

Nginx Reverse Proxy Generator Use Cases

Load-balancing an application across multiple backend instances behind one Nginx server block
Proxying a WebSocket-based real-time app (chat, live dashboards, collaborative editors) through Nginx
Terminating gRPC traffic at Nginx in front of a gRPC microservice

Common Mistakes

Enabling WebSocket support in the app but forgetting the `proxy_http_version 1.1` directive, which silently breaks the Upgrade handshake since Nginx defaults to HTTP/1.0 for proxied connections.
Trying to combine grpc_pass with WebSocket or caching directives in the same location block, which mixes incompatible proxy semantics.

Tips

If you only have one backend today, still list it inside the upstream block rather than using a bare proxy_pass to its address, adding replicas later then needs no restructuring.

Nginx Reverse Proxy Generator