208.4 Implementing Nginx as a web server and a reverse proxy

Introduction

Nginx can serve static files directly and proxy dynamic requests to application servers. Correct URI mapping and forwarded headers are central to a reliable reverse proxy.

What you should be able to do after this lesson:

• Locate, inspect, and validate Nginx configuration.
• Create a basic name-based server block.
• Serve static content with root or alias correctly.
• Proxy requests and preserve client context.
• Configure simple upstream load distribution.

Big Idea: Nginx Maps a Request Twice

For a reverse-proxied request, Nginx first selects a server and location, then constructs the URI sent upstream. Most surprising behavior comes from one of those mapping steps:

address and Host -> server block -> location -> rewritten upstream URI

Always test the exact request path and inspect the effective configuration with nginx -T.

Configuration Structure

Nginx configuration commonly lives under /etc/nginx/, with nginx.conf including additional files.

nginx -T
nginx -t

-T prints the effective configuration; -t validates syntax and referenced files.

Basic Web Server

server {
    listen 80;
    server_name example.test;
    root /srv/www/example;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

root appends the request URI to the configured path. alias replaces the matched location prefix and requires careful trailing-slash handling.

Reverse Proxy

location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

The trailing slash on proxy_pass changes URI replacement behavior. Test the exact upstream path rather than relying on intuition.

Applications should trust forwarded headers only from known proxies. Otherwise a direct client may spoof them.

Upstream Groups

upstream application {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

location /api/ {
    proxy_pass http://application;
}

Nginx can distribute requests across upstream members and apply timeout or failure settings.

By default, upstream selection is round-robin. Other methods and health behavior depend on configuration and available modules. Reverse proxying does not automatically make the application stateless; sessions, uploads, retries, and connection timeouts still require an application-aware design.

Logs and Operation

nginx -t
systemctl reload nginx
journalctl -u nginx

Access logs describe requests; error logs reveal configuration, filesystem, and upstream failures. A reload starts workers with new configuration while old workers finish existing requests.

Common Failure Boundaries

• 404: wrong root, alias, location, or upstream URI
• 403: permissions or access policy
• 502: no usable upstream connection
• 504: upstream response timeout
• redirect loop: inconsistent scheme or host handling

Guided Practice: Compare root, alias, and proxy_pass

On a lab host, configure three distinct paths:

• /static/ served with root
• /downloads/ served with alias
• /api/ forwarded to a local test application

Before every reload:

nginx -t
nginx -T | less

Request an existing and missing file from both static locations, then request /api/health. Compare the filesystem path or upstream URI produced by each directive. Verify the upstream receives the intended Host, client address, and scheme headers.

Troubleshooting Scenario

The browser requests /api/users, but the application receives /users and returns 404. The proxy_pass URI contains a trailing slash that replaces the matched /api/ prefix.

Choose the intended URI contract, adjust proxy_pass or the location, validate, reload, and test several nested paths. Increasing the upstream timeout would not repair path rewriting.

Exam Focus

• Know /etc/nginx/, nginx, nginx -t, and effective include structure.
• Distinguish a basic web server from a reverse proxy.
• Understand root, alias, location selection, and proxy_pass URI behavior.
• Preserve only trusted forwarding headers and interpret 502/504 separately from application responses.

Recap

• Validate effective configuration before reload.
• root, alias, and proxy_pass transform paths differently.
• Preserve required host, client, and scheme information for the application.
• A reverse proxy error should be separated from an application error.