Web servers and networking · Intermediate · 12 min
How to Put Nginx in Front of a Node.js App as a Reverse Proxy
By Padding · Updated 15 Nov 2026
Ubuntu 26.04.1 LTS · Nginx 1.30 · Node.js 26
You will install Node.js 26, run a small app on a local port, and configure Nginx 1.30 to pass public traffic to it with the headers your app needs.
On this page
A Node.js app can listen on a public port by itself, but you would rather not. Nginx handles slow clients, TLS, compression and static files better than most apps do, and it lets several apps share ports 80 and 443. In the usual setup, the app listens only on the server's local address, and Nginx, the reverse proxy, forwards requests to it.
In this tutorial you will install Node.js 26, run a tiny app on 127.0.0.1:3000, put Nginx in front of it, and check that the app sees the visitor's real IP address and protocol. It is the sixth tutorial in the series Your first production server.
Step 1 · Install Nginx and Node.js
Nginx comes from the nginx.org repository. If it is already installed, skip the first block. The full explanation is in /tutorials/install-nginx-on-ubuntu-26-04.
sudo apt-get update
sudo apt-get install -y curl gnupg2 ca-certificates lsb-release ubuntu-keyring xz-utils libatomic1
curl -fsSL https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://nginx.org/packages/ubuntu $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
printf 'Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n' | sudo tee /etc/apt/preferences.d/99nginx
sudo apt-get update
sudo apt-get install -y nginx
nginx -vUbuntu's own nodejs package is Node.js 22. For version 26, which is a long-term support release, install the official binary from nodejs.org. It needs xz-utils to unpack and libatomic1 to run, both installed in the first block on a minimal server. Download the archive and its checksum list, check the archive against the list, then unpack it into /usr/local.
NODE_VERSION=v26.13.1
case "$(uname -m)" in
x86_64) NODE_ARCH=x64 ;;
aarch64) NODE_ARCH=arm64 ;;
*) echo "unsupported architecture"; false ;;
esac
cd /tmp
curl -fsSLO "https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz"
curl -fsSLO "https://nodejs.org/dist/${NODE_VERSION}/SHASUMS256.txt"
grep " node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz\$" SHASUMS256.txt | sha256sum -c -
NODE_DIR="node-${NODE_VERSION}-linux-${NODE_ARCH}"
sudo tar -xJf "${NODE_DIR}.tar.xz" -C /usr/local --strip-components=1 --no-same-owner \
"${NODE_DIR}/bin" "${NODE_DIR}/include" "${NODE_DIR}/lib" "${NODE_DIR}/share"The archive also holds a CHANGELOG.md, LICENSE and README.md. Naming only bin, include, lib and share keeps them out of /usr/local. NODE_VERSION is the current 26.x release on 15 November 2026. Check nodejs.org/en/download for a newer 26.x patch and change the variable if there is one.
Check it worked
node -v
npm -vnode -v prints v26.13.1 and npm -v prints the npm that ships with it. The archive check printed node-v26.13.1-linux-<arch>.tar.xz: OK. If it printed FAILED, the download is damaged or altered, so do not use it.
Step 2 · Create a small app
The app answers every request with a JSON object that echoes the headers Nginx will pass on. It listens only on the local loopback address, so the outside world cannot reach it without going through Nginx.
mkdir -p ~/myapp
cat > ~/myapp/server.js <<'JS'
const http = require('node:http');
const server = http.createServer((req, res) => {
res.setHeader('Content-Type', 'application/json');
res.end(JSON.stringify({
message: 'Hello from Node',
host: req.headers['host'],
remoteAddress: req.socket.remoteAddress,
xRealIp: req.headers['x-real-ip'],
xForwardedFor: req.headers['x-forwarded-for'],
xForwardedProto: req.headers['x-forwarded-proto'],
}) + '\n');
});
server.listen(3000, '127.0.0.1', () => {
console.log('Listening on http://127.0.0.1:3000');
});
JSStart the app. It stays in the foreground, so leave this terminal running and open a second one for the next commands.
cd ~/myapp
node server.jsIn the second terminal, ask the app directly:
curl -s http://127.0.0.1:3000/It prints {"message":"Hello from Node","host":"127.0.0.1:3000","remoteAddress":"127.0.0.1"}. The three forwarded-header fields are absent, because nothing has set them. This is the app reached directly.
In production, run the app with systemd so it restarts and starts at boot. See /tutorials/run-an-app-as-a-systemd-service and use ExecStart=/usr/local/bin/node /home/deploy/myapp/server.js.
Step 3 · Configure Nginx as a reverse proxy
Create a server block for the site. Replace app.example.com with your own name.
Before you run it, note that the last commands delete the stock default.conf, whose welcome page would otherwise answer for your server's bare IP address. On a server that already hosts other sites, leave out the sudo rm -f /etc/nginx/conf.d/default.conf line. The block matches by server_name and works without it.
sudo tee /etc/nginx/conf.d/myapp.conf > /dev/null <<'CONF'
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
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;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
CONF
sudo rm -f /etc/nginx/conf.d/default.conf
sudo nginx -tWhat the lines do:
proxy_passsends the request to the app. There is no path after the port, so the request path passes through unchanged.proxy_http_version 1.1is required for WebSockets to the app, and for keep-alive connections to it.Hostkeeps the visitor's domain, so the app can build correct links.X-Real-IPandX-Forwarded-Forcarry the visitor's address. Without them the app only ever sees127.0.0.1.X-Forwarded-Protosays whether the visitor usedhttporhttps. After you add HTTPS, apps use it to decide on secure cookies and redirects.- The
UpgradeandConnectionlines, with themapblock, let WebSocket connections through. For ordinary requests the map setsConnection: close, so Nginx opens a new connection to the app for each request. If your app has no WebSockets, delete themapblock and both of these lines, and useproxy_set_header Connection "";instead. That lets Nginx reuse connections to the app.
The map block belongs at the http level. Files in /etc/nginx/conf.d/ are included there, so putting it beside the server block works.
Apply the configuration:
sudo nginx -t && sudo systemctl reload nginxCheck it worked
Send a request through Nginx with the right Host header:
curl -s -H 'Host: app.example.com' http://127.0.0.1/The JSON now shows "host":"app.example.com", "xRealIp":"127.0.0.1", "xForwardedFor":"127.0.0.1" and "xForwardedProto":"http". From a real client, xRealIp is that client's public address. The remoteAddress is still 127.0.0.1, because it is Nginx that connects to the app.
Troubleshooting
502 Bad Gateway: Nginx cannot reach the app. Check it is running withcurl http://127.0.0.1:3000/and that the port inproxy_passis the one the app uses.504 Gateway Time-out: the app took longer than 60 seconds to answer. Raiseproxy_read_timeoutin thelocationblock only if the app has a good reason to be slow.- The error log names the cause:
sudo tail /var/log/nginx/error.log.connect() failed (111: Connection refused)means nothing is listening on the port. - Your app shows the wrong client IP: it is reading the socket address. Many frameworks have a setting for trusting the proxy. In Express, it is
app.set('trust proxy', 'loopback').
Step 4 · Check what happens when the app is down
Stop the app with Ctrl+C in its terminal, and ask again:
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: app.example.com' http://127.0.0.1/The status is 502. Nginx is fine and the app is not. Visitors see Nginx's error page until the app returns. Restart your app, and with systemd and Restart=on-failure that happens by itself.
Next steps
- Add a certificate, so the proxy serves HTTPS and the app sees
X-Forwarded-Proto: https:/tutorials/free-https-with-lets-encrypt-and-nginx. - Spread requests across several copies of the app:
/tutorials/load-balance-with-nginx-upstream. - Keep the app running after a crash or a reboot:
/tutorials/run-an-app-as-a-systemd-service.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials