proxy_pass directive in Nginx - Commands & Configuration

Introduction

Sometimes you want your web server to forward requests to another server or service. The proxy_pass directive in nginx helps you do this by sending client requests to a different backend server.

When you want nginx to forward requests to a web application running on another server or port.

When you want to hide the real backend server from users for security or simplicity.

When you want to load balance requests between multiple backend servers.

When you want to serve static files from nginx but pass dynamic requests to an application server.

When you want to add caching or security features in front of your backend service.

Config File - nginx.conf

nginx.conf

events {}
http {
    server {
        listen 8080;

        location /app/ {
            proxy_pass http://localhost:5000/;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

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

The location /app/ block tells nginx to forward all requests starting with /app/ to the backend server at http://localhost:5000/.

The proxy_set_header lines pass the original host and client IP to the backend server, which helps with logging and security.

Commands

This command tests the nginx configuration file for syntax errors before applying it.

Terminal

sudo 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

This command reloads nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

This command sends a request to nginx on port 8080 at path /app/ to verify that proxy_pass forwards the request to the backend server.

Terminal

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

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

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

Content-Type: text/html

Content-Length: 13



Hello from app

Key Concept

If you remember nothing else from this pattern, remember: proxy_pass forwards client requests from nginx to another server or service.

Common Mistakes

Not including a trailing slash at the end of the proxy_pass URL.

Without the trailing slash, nginx appends the full original request URI to the proxy_pass URL, which can cause incorrect backend paths.

Always include a trailing slash at the end of the proxy_pass URL if you want to replace the matching part of the request URI.

Forgetting to reload nginx after changing the configuration.

Changes won't take effect until nginx reloads the configuration, so the proxy_pass won't work as expected.

Run 'sudo nginx -t' to test and then 'sudo systemctl reload nginx' to apply changes.

Not setting proxy_set_header for Host and X-Real-IP.

The backend server may not receive the correct client IP or host information, causing logging or routing issues.

Add proxy_set_header directives to pass original client info to the backend.

Summary

Use proxy_pass in nginx to forward requests to another server or service.

Test your nginx configuration with 'nginx -t' before reloading.

Reload nginx to apply changes and verify with curl requests.