How to Deploy Next.js to a VPS

#2. Nginx reverse proxy

Nginx sits on the host, terminates TLS, and proxies to the container on 127.0.0.1:3000. Keep the upstream target in its own file — the deploy script in step 5 rewrites this one line to flip traffic between releases:

copy# /etc/nginx/conf.d/nextjs-upstream.conf
upstream nextjs { server 127.0.0.1:3000; }

Then the site itself:

copy# /etc/nginx/sites-available/example.com
server {
  listen 80;
  server_name example.com;

  # Serve _next/static straight from Nginx if you bind-mount it; otherwise
  # the standalone server handles it fine.
  client_max_body_size 25m;          # bump if you accept large uploads

  location / {
    proxy_pass http://nextjs;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;      # WebSockets / HMR
    proxy_set_header Connection "upgrade";
    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;  # so Next.js knows it's HTTPS
    proxy_cache_bypass $http_upgrade;
  }
}

Enable it and reload:

copyln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

#3. HTTPS with Let's Encrypt

Certbot's Nginx plugin edits the config, requests a certificate, and sets up auto-renewal in one command. Your DNS A record must already point at the server — Let's Encrypt verifies the domain over port 80.

copyapt install -y certbot python3-certbot-nginx
certbot --nginx -d example.com -d www.example.com

Choose the redirect-HTTP-to-HTTPS option when prompted. Certbot installs a systemd timer that renews ~30 days before expiry, so you never touch it again. (Prefer Caddy's fully-automatic TLS instead? See Automatic HTTPS with Caddy.)

#4. Environment variables

Keep secrets out of the image. Put them in a .env file on the server (never commit it) and pass it in at run time:

copy# /home/deploy/app/.env
DATABASE_URL=postgres://…
AUTH_SECRET=…

One Next.js gotcha: NEXT_PUBLIC_* variables are inlined at build time, not read at runtime. If you build the image on the server that's fine, but if you build in CI you must supply those values as build args there — changing them on the box afterwards has no effect until you rebuild.

#5. Zero-downtime deploys

A plain docker restart drops every in-flight request during the swap. To avoid that, run a blue-green flip: start the new release alongside the old one on a second port, health-check it, point Nginx at it with a graceful reload (which lets existing connections drain), then retire the old container.

Save this as deploy.sh next to your .env:

copy#!/usr/bin/env bash
set -euo pipefail

IMAGE=myapp:latest
HEALTH=/                                        # any route that returns 200
UPSTREAM=/etc/nginx/conf.d/nextjs-upstream.conf
BLUE=3000; GREEN=3001

# Which slot is live right now?
if grep -q ":$BLUE;" "$UPSTREAM"; then
  LIVE=$BLUE; NEXT=$GREEN; NEXT_NAME=web-green; LIVE_NAME=web-blue
else
  LIVE=$GREEN; NEXT=$BLUE; NEXT_NAME=web-blue;  LIVE_NAME=web-green
fi

echo "→ Building $IMAGE"
docker build -t "$IMAGE" .

echo "→ Starting $NEXT_NAME on :$NEXT"
docker rm -f "$NEXT_NAME" 2>/dev/null || true
docker run -d --name "$NEXT_NAME" --restart unless-stopped \
  --env-file .env -p "127.0.0.1:$NEXT:3000" "$IMAGE"

echo "→ Waiting for health"
for i in $(seq 30); do
  curl -fsS "http://127.0.0.1:$NEXT$HEALTH" >/dev/null && break
  [ "$i" -eq 30 ] && { echo "unhealthy — rolling back"; docker rm -f "$NEXT_NAME"; exit 1; }
  sleep 1
done

echo "→ Flipping Nginx :$LIVE → :$NEXT"
sudo sed -i "s/:$LIVE;/:$NEXT;/" "$UPSTREAM"
sudo nginx -t && sudo nginx -s reload           # graceful — no dropped requests

echo "→ Retiring $LIVE_NAME"
docker rm -f "$LIVE_NAME" 2>/dev/null || true
echo "✓ Live on :$NEXT"

Now every deploy is git pull && ./deploy.sh. The script alternates between ports 3000 and 3001 on each run, so there's always a healthy container serving traffic while the next one builds and warms up.

#Adding a database

If your app needs Postgres, the simplest reliable option is a container on the same box, on a private network, never published to the internet:

copy# compose.yaml — Postgres only; the app is deployed by deploy.sh above
services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: app
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"   # localhost only

docker compose up -d, point DATABASE_URL at 127.0.0.1:5432, and back up ./pgdata (or pg_dump to off-box storage) on a schedule. For anything you can't afford to lose, a managed Postgres is worth the money.

#Troubleshooting

Build gets killed / server freezes during deploy. Almost always memory. Add swap (fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile) as a stopgap, but the real fix is the 4 GB sizing above or building off-box.

502 Bad Gateway from Nginx. The container isn't reachable on the expected port. Check it's running (docker ps), that it's published to 127.0.0.1:3000, and that the app bound to 0.0.0.0 inside the container (the HOSTNAME env in the Dockerfile).

Certificate won't issue. The A record must resolve to this server and port 80 must be open — Let's Encrypt fetches a challenge file over HTTP. Confirm with dig example.com and ufw status.

NEXT_PUBLIC_* value looks stale. It's baked in at build time. Rebuild the image after changing it; restarting the container alone won't update it.

#Verification + next steps

You're done when you can load your domain over HTTPS with a valid certificate, run ./deploy.sh and watch traffic flip to the new release with zero failed requests, and reboot the server and have everything come back up on its own (the --restart unless-stopped policy plus Nginx's systemd unit handle that).

From here, add a healthcheck route for the deploy script to hit, wire up off-box database backups, and set up log rotation. The one thing that makes or breaks the experience is the box underneath it — 2 vCPU / 4 GB is the right tier. See Best VPS for Node.js & Next.js Apps for the ranked picks.