Document nginx streaming and compression for sqlpage

examples/nginx/README.md

@@ -43,6 +43,26 @@ This service sets up a MySQL database with predefined credentials and a persiste
 
 The `nginx.conf` file contains the NGINX configuration:
 
+### Streaming and compression
+
+SQLPage streams HTML as it is generated, so browsers can start rendering before the database finishes returning rows. NGINX enables `proxy_buffering` by default, which can delay those first bytes but stores responses for slow clients. Start with a modest buffer configuration and let the proxy handle compression:
+
+```
+    proxy_buffering on;
+    proxy_buffer_size 16k;
+    proxy_buffers 4 16k;
+
+    gzip on;
+    gzip_buffers 2 4k;
+    gzip_types text/html text/plain text/css application/javascript application/json;
+
+    chunked_transfer_encoding on;
+```
+
+Keep buffering when you expect slow clients or longer SQLPage queries, increasing the buffer sizes only if responses overflow. When most users are on fast connections reading lightweight pages, consider reducing the buffer counts or flipping to `proxy_buffering off;` to minimise latency, accepting the extra load on SQLPage. See the [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) directives for more guidance.
+
+When SQLPage runs behind a reverse proxy, set `compress_responses` to `false` in its configuration (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)) so that NGINX can perform compression once at the edge.
+
 ### Rate Limiting
 
 

examples/official-site/your-first-sql-website/nginx.md

@@ -65,6 +65,23 @@ sudo systemctl reload nginx
 
 Your SQLPage instance is now hosted behind a reverse proxy using NGINX. You can access it by visiting `http://example.com`.
 
+
+### Streaming-friendly proxy settings
+
+SQLPage streams HTML by default so the browser can render results while the database is still sending rows.
+If you have slow SQL queries (you shouldn't), you can add the following directive to your location block:
+
+```nginx
+proxy_buffering off;
+```
+
+That will allow users to start seeing the top of your pages faster,
+but will increase the load on your SQLPage server, and reduce the amount of users you can serve concurrently.
+
+Refer to the official documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when tuning these values.
+
+When SQLPage sits behind a reverse proxy, set `compress_responses` to `false` [in `sqlpage.json`](https://github.com/sqlpage/SQLPage/blob/main/configuration.md) so that NGINX compresses once at the edge.
+
 ### URL Rewriting
 
 URL rewriting is a powerful feature that allows you to manipulate URLs to make them more readable, search-engine-friendly, and easy to maintain.