Deploy Next.js to a VPS the Hard Way — Every Step Other Tutorials Skip

Most Next.js tutorials end at npm run dev. The deployment section says "push to Vercel" and moves on.

That's fine until you need to own your infrastructure, keep costs under control, or just understand what's actually happening when your app goes live. This post walks through deploying a Next.js app to a bare VPS, step by step. No platform, no abstraction layer. Just you, a server, and the commands.

By the end, you'll understand every piece of the deployment pipeline. And you'll be able to decide whether you want to keep doing it manually or hand it off to a tool.

TL;DR: Deploying Next.js to a VPS manually means managing Node.js, PM2, Nginx, Certbot, deploy scripts, and GitHub Actions — plus 4 external services for monitoring and analytics. This guide walks through every step so you can decide whether to automate it or keep full control.

What You Need

• A VPS from any provider (Hetzner, DigitalOcean, Linode, Vultr). 2GB RAM minimum for a Next.js app with a build step. 4GB if you're running a database on the same box.
• A domain name pointed at your server's IP address.
• SSH access to the server.
• A Next.js app that builds successfully with npm run build on your local machine.

This guide assumes Ubuntu 22.04 or 24.04. Debian works too with minor differences.

Step 1: Set Up the Server

SSH into your new server:

ssh root@your-server-ip

Update packages and install the basics:

apt update && apt upgrade -y
apt install -y curl git ufw

Set up the firewall. Open SSH, HTTP, and HTTPS. Close everything else:

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Create a non-root user (running everything as root is asking for trouble):

adduser deploy
usermod -aG sudo deploy

Copy your SSH key to the new user:

rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy

Log out and log back in as the deploy user from now on.

Step 2: Install Node.js

Don't install Node from apt. The version in Ubuntu's default repos is usually ancient. Use the NodeSource repository:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Verify:

node --version  # Should be 20.x
npm --version

If your project uses a specific Node version (check .nvmrc or engines in package.json), match it here. Mismatched Node versions between local and server are one of the most common causes of "works on my machine" deployment failures.

Step 3: Clone and Build Your App

cd /home/deploy
git clone https://github.com/your-username/your-nextjs-app.git
cd your-nextjs-app
npm ci

npm ci instead of npm install. It installs from the lockfile exactly, which is what you want in production. npm install can resolve to different versions.

Set your environment variables:

cp .env.example .env.production
nano .env.production
# Fill in your production values: DATABASE_URL, API keys, etc.

Build:

npm run build

If this fails, fix it before continuing. Common issues: missing env vars that the build needs at compile time (Next.js bakes NEXT_PUBLIC_* variables into the client bundle during build), or native dependencies that need build tools (sudo apt install -y build-essential).

Step 4: Run the App with PM2

You need a process manager. If you just run npm start in your terminal and disconnect, the process dies. PM2 keeps it running, restarts it if it crashes, and manages logs.

sudo npm install -g pm2

Start your app:

pm2 start npm --name "nextjs-app" -- start

Check it's running:

pm2 status
pm2 logs nextjs-app

By default, Next.js starts on port 3000. Verify it's listening:

curl http://localhost:3000

Tell PM2 to start your app on server boot:

pm2 startup
pm2 save

The pm2 startup command prints a line you need to copy and run with sudo. Don't skip it, or your app won't survive a server reboot.

Step 5: Install and Configure Nginx

Nginx sits in front of your Next.js app. It handles SSL termination, serves static files, and proxies dynamic requests to your Node process.

sudo apt install -y nginx

Create a site config:

sudo nano /etc/nginx/sites-available/your-app

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        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;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/your-app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

The proxy_set_header Upgrade and Connection 'upgrade' lines are for WebSocket support. If your app uses real-time features, these headers are required.

At this point, your app should be accessible at http://yourdomain.com. No SSL yet.

Step 6: SSL with Let's Encrypt

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Certbot modifies your Nginx config to add SSL, sets up automatic certificate renewal, and redirects HTTP to HTTPS.

Verify the renewal timer is active:

sudo systemctl status certbot.timer

Certificates expire every 90 days. Certbot's timer renews them automatically. If you skip this check and the timer isn't running, your site goes down in 3 months with an expired cert. It happens more often than you'd think.

Step 7: Set Up Deployments

Your app is live. Now you need a way to update it when you push new code.

Create /home/deploy/deploy.sh:

#!/bin/bash
set -e

cd /home/deploy/your-nextjs-app

echo "Pulling latest code..."
git pull origin main

echo "Installing dependencies..."
npm ci

echo "Building..."
npm run build

echo "Restarting..."
pm2 restart nextjs-app

echo "Done."

chmod +x /home/deploy/deploy.sh

Automating with GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to VPS
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_IP }}
          username: deploy
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: /home/deploy/deploy.sh

Add SERVER_IP and SSH_PRIVATE_KEY to your repo's GitHub Secrets.

What This Doesn't Handle

The deploy script above has real gaps:

• No health check. If the new build is broken, PM2 restarts the old process, but there's a window where requests fail.
• No rollback. If the deploy breaks the app, you have to manually revert.
• No preview environments. Every push to main goes straight to production.
• Downtime during restart. PM2's restart kills the old process and starts the new one. There's a 1-3 second gap with 502 errors.

You can solve each of these individually (blue-green deploys with Nginx upstream toggling, a webhook server, PM2's cluster mode). But each solution adds complexity, and by the time you've built all of them, you've built a deployment platform. For a deeper look at how these platforms automate this pipeline, see how git-push deployments work under the hood.

Step 8: Monitoring (The Part Most Tutorials Skip)

Your app is deployed. How do you know it's still running tomorrow?

Logs: PM2 handles application logs. Rotate them or they'll fill your disk:

pm2 install pm2-logrotate

Uptime: You need something that pings your site and alerts you when it's down. Free options: UptimeRobot, Betterstack (free tier), or a cron job that curls your health endpoint. See our guide on building an uptime monitoring system for more depth.

Error tracking: When your app throws an unhandled exception in production, how do you find out? Sentry (free tier), LogRocket, or parsing PM2 logs manually. We covered the options in error tracking without Sentry.

Analytics: Google Analytics, Plausible, Umami, or similar. If you want to avoid third-party scripts entirely, see how to add web analytics without third-party scripts.

Each of these is a separate tool, a separate account, a separate dashboard.

The Full Stack of What You Just Built

Let's count:

Running on your server:

1. Node.js (runtime)
2. PM2 (process manager)
3. Nginx (reverse proxy, SSL termination)
4. Certbot (certificate renewal)
5. Git (code delivery)
6. GitHub Actions (build automation)

Still need but didn't set up: 7. Uptime monitoring (external service) 8. Error tracking (external service) 9. Analytics (external service) 10. Log management (PM2 + logrotate, or external service)

That's 6 things on your server and 4 external services for a single Next.js app.

Or: Skip All of That

The manual approach works. But there's a reason deployment platforms exist.

If you want the git push workflow without managing Nginx, PM2, Certbot, deploy scripts, and GitHub Actions yourself:

• Vercel is the obvious choice for Next.js. They built the framework. Free tier is generous. Costs scale fast with traffic.
• Coolify is open-source, self-hosted. Handles Docker, Traefik proxy, SSL, and git-push deploys. Good community.
• Dokploy is another open-source option, simpler than Coolify, focused on minimal configuration.
• Kamal (from the Rails team) deploys Docker containers to any server over SSH. Minimal abstraction.
• Temps is what we build. Single Rust binary that handles deployments plus analytics, error tracking, uptime monitoring, and session replay. One tool instead of 10. Open source and free to self-host.

The point of this tutorial isn't to talk you out of doing it manually. It's to make sure you know what "deploying to production" actually involves, so you can make an informed choice.