Nginx proxy configuration for FastAPI with WebSockets

<p>FastAPI application runs behind Nginx as a reverse proxy. Regular HTTP requests work but WebSocket connections fail with 400 or 502 errors. Need Nginx configured to properly proxy WebSocket upgrade requests.</p>

<p>Add the required upgrade headers to the Nginx location block for WebSocket support:</p> <div class="highlight"><pre><span></span><code><span class="c1"># /etc/nginx/conf.d/default.conf</span> <span class="c1"># Shared proxy settings</span> <span class="k">map</span><span class="w"> </span><span class="nv">$http_upgrade</span><span class="w"> </span><span class="nv">$connection_upgrade</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">default</span><span class="w"> </span><span class="s">upgrade</span><span class="p">;</span> <span class="w"> </span><span class="kn">''</span><span class="w"> </span><span class="s">close</span><span class="p">;</span> <span class="p">}</span> <span class="k">upstream</span><span class="w"> </span><span class="s">fastapi_backend</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">server</span><span class="w"> </span><span class="n">api</span><span class="p">:</span><span class="mi">8000</span><span class="p">;</span><span class="w"> </span><span class="c1"># Docker service name</span> <span class="w"> </span><span class="kn">keepalive</span><span class="w"> </span><span class="mi">32</span><span class="p">;</span><span class="w"> </span><span class="c1"># Persistent connections to upstream</span> <span class="p">}</span> <span class="k">server</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">listen</span><span class="w"> </span><span class="mi">80</span><span class="p">;</span> <span class="w"> </span><span class="kn">server_name</span><span class="w"> </span><span class="s">api.example.com</span><span class="p">;</span> <span class="w"> </span><span class="c1"># Redirect HTTP to HTTPS</span> <span class="w"> </span><span class="kn">return</span><span class="w"> </span><span class="mi">301</span><span class="w"> </span><span class="s">https://</span><span class="nv">$host$request_uri</span><span class="p">;</span> <span class="p">}</span> <span class="k">server</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">listen</span><span class="w"> </span><span class="mi">443</span><span class="w"> </span><span class="s">ssl</span><span class="p">;</span> <span class="w"> </span><span class="kn">server_name</span><span class="w"> </span><span class="s">api.example.com</span><span class="p">;</span> <span class="w"> </span><span class="kn">ssl_certificate</span><span class="w"> </span><span class="s">/etc/letsencrypt/live/api.example.com/fullchain.pem</span><span class="p">;</span> <span class="w"> </span><span class="kn">ssl_certificate_key</span><span class="w"> </span><span class="s">/etc/letsencrypt/live/api.example.com/privkey.pem</span><span class="p">;</span> <span class="w"> </span><span class="c1"># Regular HTTP API</span> <span class="w"> </span><span class="kn">location</span><span class="w"> </span><span class="s">/api/</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://fastapi_backend</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Host</span><span class="w"> </span><span class="nv">$host</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Real-IP</span><span class="w"> </span><span class="nv">$remote_addr</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-For</span><span class="w"> </span><span class="nv">$proxy_add_x_forwarded_for</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-Proto</span><span class="w"> </span><span class="nv">$scheme</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_http_version</span><span class="w"> </span><span class="mi">1</span><span class="s">.1</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_read_timeout</span><span class="w"> </span><span class="s">30s</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="w"> </span><span class="c1"># WebSocket endpoint</span> <span class="w"> </span><span class="kn">location</span><span class="w"> </span><span class="s">/ws/</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://fastapi_backend</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_http_version</span><span class="w"> </span><span class="mi">1</span><span class="s">.1</span><span class="p">;</span> <span class="w"> </span><span class="c1"># Critical: these headers enable WebSocket upgrade</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Upgrade</span><span class="w"> </span><span class="nv">$http_upgrade</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Connection</span><span class="w"> </span><span class="nv">$connection_upgrade</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Host</span><span class="w"> </span><span class="nv">$host</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Real-IP</span><span class="w"> </span><span class="nv">$remote_addr</span><span class="p">;</span> <span class="w"> </span><span class="c1"># Longer timeout for persistent WebSocket connections</span> <span class="w"> </span><span class="kn">proxy_read_timeout</span><span class="w"> </span><span class="s">3600s</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_send_timeout</span><span class="w"> </span><span class="s">3600s</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="w"> </span><span class="c1"># Server-Sent Events</span> <span class="w"> </span><span class="kn">location</span><span class="w"> </span><span class="s">/events/</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://fastapi_backend</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_http_version</span><span class="w"> </span><span class="mi">1</span><span class="s">.1</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Connection</span><span class="w"> </span><span class="s">''</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_cache</span><span class="w"> </span><span class="no">off</span><span class="p">;</span> <span class="w"> </span><span class="kn">proxy_buffering</span><span class="w"> </span><span class="no">off</span><span class="p">;</span><span class="w"> </span><span class="c1"># Critical: disable buffering for SSE</span> <span class="w"> </span><span class="kn">proxy_read_timeout</span><span class="w"> </span><span class="s">3600s</span><span class="p">;</span> <span class="w"> </span><span class="kn">add_header</span><span class="w"> </span><span class="s">X-Accel-Buffering</span><span class="w"> </span><span class="s">no</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="p">}</span> </code></pre></div> <p>The <code>map</code> block dynamically sets <code>Connection: upgrade</code> only when an <code>Upgrade</code> header is present. Without <code>proxy_http_version 1.1</code>, keepalive and WebSocket upgrades don't work. For SSE, <code>proxy_buffering off</code> is mandatory — buffering delays event delivery.</p>