NGINX Reverse Proxy Setup

This example assumes NGINX runs on the host and your own application is reachable from that host at 127.0.0.1:3000. If NGINX runs in Docker, use the upstream service name on a shared Docker network.

Confirm the App Responds

From the machine or container running NGINX, verify that the app answers requests at the address you intend to proxy. A host address and a container address can resolve to different places.

curl -I http://127.0.0.1:3000/

Expected checkpoint: the app returns the status and body you expect for that path. A refusal means there is no listener at that address. A 404 can still confirm a reachable app if the route is wrong.

Add a Server Block

Use this simple HTTP example or the reverse proxy config generator as a starting point on your own server. Replace the sample hostname with the hostname you control. Configure TLS before serving sensitive traffic over a public connection.

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Run a Local Reverse Proxy Lab

This local exercise uses a Python upstream on loopback and NGINX on a different loopback port. It keeps the example separate from your production config. Run it on a machine with NGINX, Python 3 and curl installed, using ports 3000 and 8088 when they are free.

lab=$(mktemp -d)
mkdir "$lab/www"
printf 'proxy-lab-ok\n' > "$lab/www/index.html"
python3 -m http.server 3000 --bind 127.0.0.1 --directory "$lab/www" &
app_pid=$!
curl --noproxy '*' --retry 3 --retry-connrefused -fsS http://127.0.0.1:3000/

The direct check should print proxy-lab-ok. Save the following as $lab/nginx.conf.

pid nginx.pid;
error_log error.log;
events {}
http {
    access_log off;
    server {
        listen 127.0.0.1:8088;
        location / {
            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}
nginx -p "$lab/" -c nginx.conf -t
nginx -p "$lab/" -c nginx.conf
curl --noproxy '*' -fsS http://127.0.0.1:8088/

Expect the configuration test to pass and the last request to print proxy-lab-ok again. If you want to reproduce a refused connection, keep this shell open and follow the 502 exercise. Otherwise stop the lab with:

nginx -p "$lab/" -c nginx.conf -s stop
kill "$app_pid"

When you map a prefix, a proxy_pass with a URI can replace the matching location prefix. For example, in location /api/, proxy_pass http://127.0.0.1:3000/; sends /api/status as /status. Without the trailing URI, that request retains /api/status. Test both the direct and proxied routes before reloading a production site.

When NGINX Runs in Docker

Attach both services to the same Compose network. If your app service is named app and listens on port 3000, the proxy upstream is http://app:3000. Use the container port. Inside NGINX, 127.0.0.1 refers to the NGINX container itself.

Run docker compose exec nginx nginx -t using the actual NGINX service name. After it passes, reload with docker compose exec nginx nginx -s reload.

Expected checkpoint: from the NGINX network, a request to http://app:3000/ returns the app response. The app must listen on its container interface. Use a diagnostic container on the same network if the NGINX image has no HTTP client.

Test and Reload

Run nginx -t on the host. Reload only after the configuration passes. Check your own domain in a browser and compare the result with the direct upstream check. Use your installation’s service manager or container command to reload the process.

curl -i -H "Host: app.example.com" http://127.0.0.1/

Expected checkpoint: the syntax check passes, and the proxied request returns the same application response as the direct request. For the Docker variant, use docker compose exec nginx nginx -t and test the host port you published.