From e3c93333ea234b900c9cf244b5edfe2b264d5cc2 Mon Sep 17 00:00:00 2001 From: SnapOtter Date: Tue, 21 Jul 2026 18:40:39 +0800 Subject: [PATCH] docs(deploy): note that proxy response buffering stalls downloads (#607) Document that a response-buffering reverse proxy is the usual cause of a self-hosted download that starts but never finishes, point at the X-Accel-Buffering: no safety net (#604), and call out downloads alongside SSE in the nginx and Caddy examples. Refs #590 --- apps/docs/guide/deployment.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/apps/docs/guide/deployment.md b/apps/docs/guide/deployment.md index 7d85bd87..acc451d6 100644 --- a/apps/docs/guide/deployment.md +++ b/apps/docs/guide/deployment.md @@ -480,6 +480,8 @@ curl http://localhost:1349/api/v1/health SnapOtter sets `TRUST_PROXY=true` by default so rate limiting and logging use the real client IP from `X-Forwarded-For` headers. +Two things matter for every proxy below: allow large request bodies (uploads), and do not buffer responses. A response-buffering proxy breaks SSE progress and, more visibly, makes a large file download "start but never finish", because the proxy holds the whole file before passing it on. SnapOtter sends `X-Accel-Buffering: no` on downloads so nginx streams them even if buffering is left on elsewhere, but proxies other than nginx need response buffering disabled explicitly (shown in each config below). If a download stalls partway, a buffering proxy in front is the first thing to check. + ### Nginx {#nginx} ```nginx @@ -500,7 +502,8 @@ server { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - # SSE support (batch progress, feature install progress) + # Stream responses instead of buffering: needed for SSE progress + # (batch, AI, feature installs) and for large file downloads. proxy_buffering off; proxy_read_timeout 300s; } @@ -544,7 +547,7 @@ images.example.com { } ``` -`flush_interval -1` disables response buffering, which is required for SSE progress events (batch processing, AI tools, feature installs). The extended timeouts allow large file uploads to complete without Caddy closing the connection early. +`flush_interval -1` disables response buffering, which is required for SSE progress events (batch processing, AI tools, feature installs) and for large file downloads to stream through instead of stalling. The extended timeouts allow large file uploads to complete without Caddy closing the connection early. ### Cloudflare Tunnels {#cloudflare-tunnels}