Deploy a Nuxt Application on a VPS

Why Self-Host Nuxt on a VPS?

Concrete Benefits of a Self-Hosted Nuxt

• server/api server routes with no per-call billing.
• SSR and Vue 3 hydration served from a persistent, stable Node server.
• Portable Nitro build (node-server) easy to containerize and reproduce.
• Route caching and routeRules rules (SSR, SSG, ISR, SWR) controlled on the server side.
• Pooling of several Nuxt apps on a single VPS behind Nginx.
• Runtime environment variables (runtimeConfig) managed directly on your own server.
• Full control over HTTP headers (CSP, HSTS, cache-control) via Nitro middleware.

Hardware and Software Prerequisites

Deploy Nuxt Step by Step

1. 01

   Configure the Project for Node

   Set the Nitro preset in nuxt.config.ts:

   export default defineNuxtConfig({
     nitro: { preset: 'node-server' }
   })

   Declare your secrets in runtimeConfig on the server side only — never in runtimeConfig.public. On the VPS, install Node.js 20 LTS via nvm install 20 && nvm use 20 && nvm alias default 20, then PM2 globally: npm install -g pm2.

2. 02

   Build the Application

   Clone the repository and install dependencies:

   git clone https://git.yourdomain.com/your-org/your-app.git /srv/nuxt-app
   cd /srv/nuxt-app
   npm ci
   npm run build

   Nitro produces a self-contained .output folder containing server/index.mjs and static assets in .output/public. This folder is all the VPS needs to serve the application in production — you can also assemble it in CI and transfer it by rsync to avoid building on the server.

3. 03

   Create the Environment File

   Create /srv/nuxt-app/.env with your runtime variables. All variables prefixed NUXT_ override the corresponding keys in runtimeConfig at startup:

   NUXT_MY_SECRET_KEY=production-value
   NITRO_HOST=0.0.0.0
   NITRO_PORT=3000

   Never commit this file. Make sure it belongs to the user running PM2 and is readable only by that user (chmod 600).

4. 04

   Launch the Nitro Server with PM2

   Start the application and configure automatic startup:

   pm2 start /srv/nuxt-app/.output/server/index.mjs \
     --name nuxt-app \
     --env-file /srv/nuxt-app/.env
   pm2 save
   pm2 startup

   The pm2 startup command displays a line to copy-paste to create the systemd service. Run it with administrator rights. Verify the application is running: pm2 status should show the online state.

5. 05

   Configure Nginx as a Reverse Proxy

   Create /etc/nginx/sites-available/nuxt-app:

   server {
       listen 80;
       server_name yourdomain.com www.yourdomain.com;
   
       # Hashed assets: long cache, served directly
       location /_nuxt/ {
           root /srv/nuxt-app/.output/public;
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
   
       # Static public files
       location /favicon.ico {
           root /srv/nuxt-app/.output/public;
       }
   
       # Everything else → Nitro
       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 and test the configuration: ln -s /etc/nginx/sites-available/nuxt-app /etc/nginx/sites-enabled/ && nginx -t && systemctl reload nginx.

6. 06

   Enable HTTPS with Let's Encrypt

   Install Certbot and the Nginx plugin, then generate the certificate:

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

   Certbot automatically modifies the Nginx block to listen on port 443 and force HTTP → HTTPS redirect. Verify that X-Forwarded-Proto is correctly forwarded to Nitro — without it, useRequestHeaders() on the server side and protocol-based redirects may behave incorrectly. Automatic renewal is managed by Certbot's systemd timer, checkable with systemctl status certbot.timer.

7. 07

   Update Without Service Interruption

   For an update, PM2 reload (not restart) guarantees continuity:

   cd /srv/nuxt-app
   git pull
   npm ci
   npm run build
   pm2 reload nuxt-app

   PM2 starts the new version, waits for it to respond, then cuts the old one: zero downtime. For a rollback, revert to the previous commit, rebuild and reload. If the build happens in CI, transfer only the .output folder via rsync and reload without rebuilding on the server.

Optimize Rendering with routeRules

Nitro server vs Docker vs Vercel/Netlify for hosting Nuxt

Scroll the table

Troubleshooting: Common Production Errors