Streaming and chunked transfer in Nginx - Commands & Configuration

Introduction

Sometimes, web servers need to send data to browsers or clients as it is generated, without waiting for the whole content to be ready. Streaming and chunked transfer let nginx send data in pieces, so users start receiving content faster and the server uses memory efficiently.

When serving live video or audio streams that are generated on the fly.

When delivering large files without loading them fully into memory first.

When proxying requests to backend servers that send data slowly or in parts.

When you want to reduce latency so users see content as soon as possible.

When handling APIs that send data in multiple parts or events.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    server {
        listen 8080;

        location /stream {
            # Enable chunked transfer encoding
            chunked_transfer_encoding on;

            # Disable buffering to send data immediately
            proxy_buffering off;

            # Proxy to a backend that streams data
            proxy_pass http://localhost:9000;
        }
    }
}

This configuration sets up an nginx server listening on port 8080.

The /stream location enables chunked_transfer_encoding on; so nginx sends data in chunks.

proxy_buffering off; disables buffering so data is sent immediately as it arrives from the backend.

proxy_pass forwards requests to a backend server on port 9000 that streams data.

Commands

Check the nginx configuration file for syntax errors before starting or reloading nginx.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request to the streaming endpoint to verify that data is received in chunks.

Terminal

curl -i http://localhost:8080/stream

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Transfer-Encoding: chunked

Content-Type: text/plain



4

Wiki

5

pedia

E

 in


chunks.

0

Key Concept

If you remember nothing else from this pattern, remember: enabling chunked transfer and disabling buffering lets nginx send data to clients immediately in small pieces as it arrives.

Common Mistakes

Not disabling proxy_buffering when expecting streaming data.

Nginx buffers the entire response before sending, causing delays and defeating streaming.

Set proxy_buffering off; in the location block to send data immediately.

Forgetting to enable chunked_transfer_encoding.

Without chunked transfer encoding, nginx may not send data in chunks, causing clients to wait.

Add chunked_transfer_encoding on; to enable chunked data sending.

Testing with curl without the -i flag to see headers.

You miss seeing the Transfer-Encoding header that confirms chunked transfer.

Use curl -i to see HTTP headers and verify chunked transfer encoding.

Summary

Configure nginx with chunked_transfer_encoding on and proxy_buffering off to enable streaming.

Reload nginx after configuration changes to apply them without downtime.

Test the streaming endpoint with curl -i to confirm chunked transfer encoding is active.