Upstream blocks in Nginx - Commands & Configuration

Introduction

When you want to send user requests to multiple servers to share the work, you use upstream blocks in nginx. They help balance traffic so no single server gets too busy.

When you have a website running on several servers and want nginx to send visitors to any of them.

When you want to improve your website speed by spreading requests across multiple backend servers.

When you want to keep your site working even if one server stops responding.

When you want to test a new server by sending some traffic to it without changing your main site.

When you want to organize your backend servers under one name for easier management.

Config File - nginx.conf

nginx.conf

http {
    upstream myapp {
        server 192.168.1.10:8080;
        server 192.168.1.11:8080;
        server 192.168.1.12:8080;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://myapp;
        }
    }
}

The upstream block named myapp lists three backend servers by IP and port. This tells nginx to send requests to any of these servers.

The server block listens on port 80 and forwards all requests to the upstream group myapp using proxy_pass.

Commands

Check the nginx configuration file for syntax errors before restarting 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 service.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a simple HTTP request to localhost to verify nginx is forwarding requests to the upstream servers.

Terminal

curl -I http://localhost

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: upstream blocks let nginx send user requests to multiple backend servers to share the load and improve reliability.

Common Mistakes

Forgetting to reload nginx after changing the upstream block.

Nginx keeps using the old configuration until reloaded, so changes won't take effect.

Always run 'nginx -t' to check config, then 'systemctl reload nginx' to apply changes.

Using incorrect IP addresses or ports in the upstream block.

Nginx cannot connect to backend servers if addresses or ports are wrong, causing errors or no response.

Verify backend server IPs and ports are correct and reachable before adding them.

Not using the upstream block name correctly in proxy_pass (e.g., missing 'http://' prefix).

Nginx will fail to proxy requests if the upstream name is not properly referenced.

Always use 'proxy_pass http://upstream_name;' to reference the upstream group.

Summary

Define backend servers inside an upstream block to group them under one name.

Use proxy_pass with the upstream name to forward requests to these servers.

Always test configuration syntax and reload nginx to apply changes safely.