Nuxt 4 + Prisma (SQLite) on Ubuntu 24.04 LTS
with NGINX + PM2 + Docker

The Perfect Ubuntu 24.04 LTS Server

NGINX reverse proxy + Node 24 LTS (NVM) + PM2 + Docker

This guide shows you how to deploy a production-ready Nuxt 4 application with Prisma + SQLite on Ubuntu 24.04 LTS . Perfect for developers who want a secure, fast, and scalable web server with modern tooling.

Quick checklist

1. Secure access first: create a non-root sudo user, set up SSH keys, install Tailscale VPN, and verify you can SSH over Tailscale before tightening firewalls.
2. Lock down SSH: disable password auth + root login, and restrict port 22 to tailscale0 only (public SSH closed).
3. Harden the base OS: update packages, enable unattended security upgrades, set timezone, and install baseline tooling.
4. Install NGINX (Ubuntu repo is fine).
5. Install Node 24 with NVM; enable pnpm via corepack; install PM2 (+ log rotation).
6. NGINX config (in order!): create prerequisite files first (connection_upgrade.conf, admin-tailscale-only.conf), create app directory, add HTTP-only config, run Certbot for SSL, then upgrade to full HTTPS config.
7. Deploy: upload the deploy folder, install prod deps with a frozen lockfile, generate Prisma client, run migrations/preflight checks.
8. Run: start via PM2, enable startup, verify health endpoint and logs.
9. Optional: Docker for Plausible and other services (bind published ports to 127.0.0.1 to avoid Docker+UFW surprises).

Why Ubuntu 24.04 LTS?

Before You Begin: Prepare Your Local Machine (Recommended: Ubuntu Desktop).

A) Install Required Tools on Your Laptop

# Ubuntu Desktop may not have curl pre-installed
sudo apt update
sudo apt install -y curl openssh-client

# Verify SSH is available
ssh -V

B) Generate an SSH Key Pair (Ed25519)

If you don't already have an SSH key, generate one now. Ed25519 is recommended for its security and performance.

# Generate a new SSH key pair
# The -C flag adds a comment (use your email or identifier)
ssh-keygen -t ed25519 -C "{{tutorial.sudouser}}@laptop"

# When prompted:
#   - Press Enter to accept default location (~/.ssh/id_ed25519)
#   - Enter a strong passphrase (recommended) or press Enter for no passphrase

# View your public key (you'll copy this to the VPS later)
cat ~/.ssh/id_ed25519.pub

# Optional: Start ssh-agent and add your key (so you don't type passphrase every time)
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Verify the key was added
ssh-add -l

C) Install Tailscale VPN on Your Laptop

# Log out of the old Tailscale account
sudo tailscale logout

# Then connect to your new account
sudo tailscale up
# This will print a new auth URL — open it and log in with your new account

# Install Tailscale on your laptop (first device on your Tailnet)
curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl enable --now tailscaled

# Connect to your Tailnet
sudo tailscale up

# This prints an auth URL — open it in your browser to link this device.
# You must be logged in to tailscale.com for the link to work.

# Verify connection
tailscale status
tailscale ip -4   # Shows your laptop's Tailscale IP (e.g., {{tutorial.tailscaleip}})

0) Secure Access First (SSH keys + Tailscale + lock down SSH)

A) First Login and Create a Non-Root Sudo User

Initial connection: Most VPS providers give you root access or an initial user. SSH into your server using the credentials from your provider:

# Connect to VPS using public IP (first time only)
# Use root or the initial user your provider created
ssh root@{{tutorial.ipaddress}}

# Or if your provider created an initial user:
# ssh ubuntu@{{tutorial.ipaddress}}

Create your sudo user: We create a dedicated user for daily administration. adduser will prompt for a password — set a strong password even though we disable SSH password login later .

# Create the user (you'll be prompted for password and user info)
sudo adduser {{tutorial.sudouser}}
# → Enter a STRONG password (you'll need it for sudo and console access)
# → Press Enter to skip Full Name, Room Number, etc. (or fill in)

# Add user to sudo group
sudo usermod -aG sudo {{tutorial.sudouser}}

# Switch to the new user
su - {{tutorial.sudouser}}
# → Enter the password you just created

# Verify sudo works (enter your password when prompted)
sudo whoami  # Should output: root

B) Add Your SSH Public Key to the VPS

Now copy your public key from your laptop to the VPS. You have two options:

# Option 1: If ssh-copy-id works (need password auth still enabled)
# Run this in a LOCAL terminal on your laptop (not on the VPS):
ssh-copy-id {{tutorial.sudouser}}@{{tutorial.ipaddress}}
# When prompted for a password, enter your VPS user password (not the SSH key passphrase)

# Option 2: Manually paste the key (on the VPS as your sudo user):
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
# Paste your public key (from: cat ~/.ssh/id_ed25519.pub on your laptop)
# Save and exit (Ctrl+X, Y, Enter)
chmod 600 ~/.ssh/authorized_keys

ssh {{tutorial.sudouser}}@{{tutorial.ipaddress}}

C) Install and Bring Up Tailscale (on VPS)

# Install Tailscale on the VPS
curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl enable --now tailscaled

# Bring the VPS into your tailnet (and enable Tailscale SSH)
# IMPORTANT: Hostname must use hyphens, NOT dots!
#   ✅ example-com-vps  (correct)
#   ❌ example.com-vps  (invalid - dots not allowed)
sudo tailscale up --ssh --advertise-tags=tag:web --hostname {{tutorial.tsHostname()}}

# Show your Tailscale IPv4 (100.x by default)
tailscale ip -4
tailscale status

# If you forgot --ssh or need to change settings:
sudo tailscale up --ssh --advertise-tags=tag:web --hostname {{tutorial.tsHostname()}} --reset

D) Set Tailscale ACL Policy for SSH (Admin Console)

Go to Tailscale Admin → Access controls . You need both an acls rule (network access) and an ssh rule (Tailscale SSH).

In the Tailscale admin console, go to Access Controls → click "Edit access controls" (JSON editor). Replace the entire default policy with this — do not try to add rules via the UI, paste the full JSON:

{
  "tagOwners": {
    "tag:web": ["autogroup:admin"]
  },
  "acls": [
    {
      "action": "accept",
      "src":    ["autogroup:admin"],
      "dst":    ["tag:web:22", "tag:web:80", "tag:web:443"]
    }
  ],
  "ssh": [
    {
      "action": "accept",
      "src":    ["autogroup:admin"],
      "dst":    ["tag:web"],
      "users":  ["{{tutorial.sudouser}}", "root"]
    }
  ]
}

E) Test SSH over Tailscale (before locking down public SSH)

From your laptop, test Tailscale SSH connection. Use tailscale ssh (not plain ssh) — this uses Tailscale's built-in SSH authenticated via your Tailscale identity, not SSH keys.

# From your laptop — use "tailscale ssh" (not plain "ssh"):
tailscale ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}

# You should see the Ubuntu welcome banner and a shell prompt.
# If this works, Tailscale SSH is fully functional!

ssh-keygen -R {{tutorial.tsHostname()}}

# Check if the VPS is reachable at all:
tailscale ping {{tutorial.tsHostname()}}

# If ping works, try SSH by IP:
tailscale ssh {{tutorial.sudouser}}@$(tailscale ip -4 {{tutorial.tsHostname()}})

ssh-keygen -t ed25519 -C "your-email@example.com"

F) Lock down SSH + Firewall (close public port 22)

Step 1: Harden SSH server config

sudo nano /etc/ssh/sshd_config.d/99-hardening.conf

PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
UsePAM yes
MaxAuthTries 3
LoginGraceTime 30
AllowUsers {{tutorial.sudouser}}
X11Forwarding no
AllowAgentForwarding no

# Reload SSH
sudo systemctl reload ssh

Step 2: Configure firewall — Hetzner Cloud Firewall OR UFW (pick one)

# This should timeout (SSH blocked from public internet) — that's correct!
nc -vz {{tutorial.ipaddress}} 22

# This should still work (Tailscale SSH bypasses the firewall)
tailscale ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}

# Check current status (should be inactive on fresh install)
sudo ufw status

# Set default policies (explicit is better than implicit)
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow public web traffic
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Remove any public SSH rules (ignore errors if not present)
sudo ufw delete allow ssh || true
sudo ufw delete allow 22/tcp || true

# Allow SSH ONLY via Tailscale interface (not public internet)
sudo ufw allow in on tailscale0 to any port 22 proto tcp

# Enable firewall
sudo ufw enable

# Verify configuration
sudo ufw status verbose

# Check status
sudo ufw status verbose
sudo ufw status numbered    # Shows rule numbers for deletion

# Temporarily disable firewall (for troubleshooting)
sudo ufw disable

# Delete a specific rule by number
sudo ufw delete 3           # Deletes rule #3

# Reset to defaults (removes all rules!)
sudo ufw reset

# Install Fail2Ban
sudo apt install -y fail2ban

# Enable and start service
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

# Create local config (never edit jail.conf directly)
sudo nano /etc/fail2ban/jail.local

[DEFAULT]
# Ban for 1 hour (increase for repeat offenders)
bantime = 1h
# 5 failures within 10 minutes triggers ban
findtime = 10m
maxretry = 5

# Whitelist localhost and Tailscale CGNAT range so you never lock yourself out
ignoreip = 127.0.0.1/8 ::1 100.64.0.0/10

# Use nftables for banning (works without UFW)
banaction = nftables-multiport

# Handle IPv6 addresses automatically
allowipv6 = auto

# Let Fail2Ban pick the best log backend
backend = auto

# Disable SSH jail (we use Tailscale instead)
[sshd]
enabled = false

# NGINX rate limiting - ban IPs with too many requests
[nginx-limit-req]
enabled = true
port = http,https
filter = nginx-limit-req
logpath = /var/log/nginx/error.log
maxretry = 10
findtime = 1m
bantime = 1h

# NGINX bad bots - block scanners looking for exploits
[nginx-badbots]
enabled = true
port = http,https
filter = nginx-badbots
logpath = /var/log/nginx/access.log
maxretry = 2
findtime = 1d
bantime = 1w

# NGINX basic auth brute force (disable if you don't use HTTP basic auth)
# [nginx-http-auth]
# enabled = true
# port = http,https
# filter = nginx-http-auth
# logpath = /var/log/nginx/error.log
# maxretry = 5
# findtime = 5m
# bantime = 1h

# Recidive jail - escalate bans for repeat offenders
# (bans IPs that keep getting banned by other jails)
[recidive]
enabled = true
logpath = /var/log/fail2ban.log
banaction = nftables-multiport
bantime = 1w
findtime = 1d
maxretry = 5

# Create custom filter for exploit scanners
sudo nano /etc/fail2ban/filter.d/nginx-badbots.conf

[Definition]
# Block requests for common exploit paths.
# Each line MUST start with ^ — Fail2Ban crashes on startup with
# "No failure-id group" if  is missing from any regex line.
#
# Assumes default NGINX log_format:
#   IP - - [date] "GET /path HTTP/1.1" 404 ...
failregex =
  ^ - .*"(GET|POST|HEAD) .*(/wp-admin|/wp-login|/wp-content|/wp-includes|/xmlrpc\.php|/wp-json).*" .*$
  ^ - .*"(GET|POST|HEAD) .*(/phpmyadmin|/phpMyAdmin|/pma|/adminer).*" .*$
  ^ - .*"(GET|POST|HEAD) .*(/\.git/|/\.env|/\.aws|/\.ssh|/\.config|/\.svn|/\.htaccess|/\.htpasswd).*" .*$
  ^ - .*"(GET|POST|HEAD) .*(/cgi-bin/|/server-status|/actuator|/solr|/vendor|/telescope|/debug|/console).*" .*$
  ^ - .*"(GET|POST) .*\.(php|asp|aspx|jsp|cgi)(\?.*)?" (400|403|404) .*$
ignoreregex =

# Dry-run the regex against your actual access log:
sudo fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/nginx-badbots.conf

# Verify rate limit zones exist (created in Section 6A prerequisites):
cat /etc/nginx/conf.d/00-rate-limit.conf

# Should show:
# limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;
# limit_req_zone $binary_remote_addr zone=login:10m   rate=2r/s;

# If the file doesn't exist, create it now:
# sudo nano /etc/nginx/conf.d/00-rate-limit.conf

# Verify and reload
sudo nginx -t
sudo systemctl reload nginx

# Restart Fail2Ban
sudo systemctl restart fail2ban

# Check status — you should see nginx-limit-req, nginx-badbots, recidive
sudo fail2ban-client status

# Check specific jail status
sudo fail2ban-client status nginx-limit-req
sudo fail2ban-client status nginx-badbots
sudo fail2ban-client status recidive

# Verify nftables rules are created (Fail2Ban creates its own table)
sudo nft list tables
# You should see: table inet f2b-table

# Inspect the Fail2Ban nftables rules
sudo nft list table inet f2b-table

# Manually unban an IP (if needed)
sudo fail2ban-client set nginx-limit-req unbanip 1.2.3.4

# Watch Fail2Ban log
sudo tail -f /var/log/fail2ban.log

# Check service status and recent logs:
sudo systemctl status fail2ban --no-pager
sudo journalctl -u fail2ban -n 200 --no-pager -o cat

# Check Fail2Ban's own log:
sudo tail -n 200 /var/log/fail2ban.log

sudo systemctl restart fail2ban
sleep 5
sudo fail2ban-client status

# Shows how many lines match (and how many don't):
sudo fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/nginx-badbots.conf

# Test a single log line:
echo '1.2.3.4 - - [13/Feb/2026:09:34:42 +0100] "GET /wp-login.php HTTP/1.1" 404 162' | \
  sudo fail2ban-regex - /etc/fail2ban/filter.d/nginx-badbots.conf

# Edit sysctl configuration
sudo nano /etc/sysctl.conf

# Add or uncomment these lines:

# === IP Spoofing protection (✅ Ubuntu default) ===
net.ipv4.conf.all.rp_filter = 1
net.ipv4.conf.default.rp_filter = 1

# === Ignore ICMP broadcast requests (smurf attack prevention) ===
net.ipv4.icmp_echo_ignore_broadcasts = 1

# === Disable source packet routing ===
net.ipv4.conf.all.accept_source_route = 0
net.ipv6.conf.all.accept_source_route = 0
net.ipv4.conf.default.accept_source_route = 0
net.ipv6.conf.default.accept_source_route = 0

# === Disable send redirects (prevents MITM) ===
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.default.send_redirects = 0

# === SYN flood protection (✅ syncookies is Ubuntu default) ===
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.tcp_synack_retries = 2
net.ipv4.tcp_syn_retries = 5

# === Log suspicious packets (martians) ===
net.ipv4.conf.all.log_martians = 1
net.ipv4.icmp_ignore_bogus_error_responses = 1

# === Ignore ICMP redirects (prevents routing attacks) ===
net.ipv4.conf.all.accept_redirects = 0
net.ipv6.conf.all.accept_redirects = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv6.conf.default.accept_redirects = 0

# === OPTIONAL: Ignore ALL pings (stealth mode) ===
# ⚠️ This can break monitoring tools and make debugging harder
# Uncomment only if you specifically need to hide from ping scans:
# net.ipv4.icmp_echo_ignore_all = 1

# Apply changes
sudo sysctl -p

# Verify a setting
sysctl net.ipv4.tcp_syncookies

# On your LAPTOP — create/edit the SSH config file:
nano ~/.ssh/config

# Add this block (adjust values to match your setup):
Host {{tutorial.tsHostname()}}
  HostName {{tutorial.tsHostname()}}
  User {{tutorial.sudouser}}
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

# Set correct permissions (SSH requires this)
chmod 600 ~/.ssh/config

# rsync for deployments (recommended — efficient, resumable)
rsync -avz --progress ./{{tutorial.deploydir}}/ {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:/var/www/{{tutorial.domain}}/app/

# Copy a single file
scp ./myfile.txt {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:/home/{{tutorial.sudouser}}/

# Copy a directory recursively
scp -r ./{{tutorial.deploydir}}/ {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:/var/www/{{tutorial.domain}}/app/

# SSH into your server (use this to reconnect anytime)
ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}

# Or use Tailscale's built-in SSH client
tailscale ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}

# Check Tailscale connection status
tailscale status

# Show your devices' Tailscale IPs
tailscale ip -4
tailscale ip -4 {{tutorial.tsHostname()}}

# Ping the VPS over Tailscale
tailscale ping {{tutorial.tsHostname()}}

# Restart the server (graceful)
sudo reboot

# Shutdown the server
sudo shutdown now

# Scheduled shutdown in 5 minutes
sudo shutdown +5 "Server going down for maintenance"

# Cancel scheduled shutdown
sudo shutdown -c

# Restart NGINX
sudo systemctl restart nginx

# Restart your Nuxt app (via PM2)
pm2 restart {{tutorial.appname}}

# View server uptime
uptime

# If Tailscale disconnects, bring it back up
sudo tailscale up --ssh --advertise-tags=tag:web --hostname {{tutorial.tsHostname()}}

# Check Tailscale service status
sudo systemctl status tailscaled

# Restart Tailscale service
sudo systemctl restart tailscaled

# View Tailscale logs
sudo journalctl -u tailscaled -f

# Force re-authentication (if needed)
sudo tailscale logout
sudo tailscale up --ssh --advertise-tags=tag:web --hostname {{tutorial.tsHostname()}}

ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}

1) Initial Server Setup

# Update system packages
sudo apt update && sudo apt full-upgrade -y

# Install essential build tools and utilities
sudo apt install -y curl git wget build-essential ca-certificates gnupg lsof unzip \
  htop ncdu lnav

# Set timezone (adjust for your location)
sudo timedatectl set-timezone Europe/Stockholm

# Enable automatic security upgrades (recommended)
sudo apt install -y unattended-upgrades needrestart
sudo dpkg-reconfigure --priority=low unattended-upgrades

# Firewall note:
# - Ports 80/443 should be allowed publicly
# - Port 22 should be allowed ONLY via Tailscale (see Step 0)
# If using UFW: sudo ufw status verbose
# If using Hetzner Cloud Firewall: check the Hetzner console

Security Note: With SSH restricted to Tailscale only (Step 0), you don't need Fail2ban for SSH or a custom SSH port. However, Fail2ban is still recommended for HTTP/HTTPS rate limiting and bot protection — most VPS providers (including Hetzner and HostUp) only include L3/L4 DDoS protection, which does not filter application-layer (L7) attacks on HTTPS websites. See the optional Fail2Ban section in Step 0 for setup.

2) Install NGINX

# Option A (recommended): Ubuntu repository (stable, security supported)
sudo apt install -y nginx

# Option B (optional): Official NGINX repository (newer features)
curl 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] \
http://nginx.org/packages/ubuntu $(lsb_release -cs) nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list
sudo apt update
sudo apt install -y nginx

# Start and enable NGINX
sudo systemctl start nginx
sudo systemctl enable nginx

# Verify installation
nginx -v
curl http://localhost  # Should show NGINX welcome page

3) Install Node.js 24 with NVM (Multi-Version Support)

Why NVM? Node Version Manager allows you to install and switch between multiple Node.js versions. Perfect for servers hosting multiple applications with different Node requirements.

Which Node version? Use the same version as your local development environment for consistency. Check with node --version on your laptop. Both Node 22 and 24 are LTS versions that work well with Nuxt 4. This tutorial uses Node 24.

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Load NVM (add to ~/.bashrc for persistence)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node.js 24 LTS
nvm install 24
nvm use 24
nvm alias default 24

# Verify installation
node --version  # Should show v24.x.x
npm --version

# Install multiple versions if needed (optional)
# nvm install 20    # For apps requiring Node 20
# nvm install 18    # For apps requiring Node 18
# nvm list          # Show all installed versions

4) Install pnpm and PM2

# Enable corepack for pnpm
corepack enable
corepack prepare pnpm@latest --activate

# Verify pnpm
pnpm --version

# Install PM2 globally (NO sudo - NVM installs to ~/.nvm which you own)
npm install -g pm2

# Verify PM2
pm2 --version

# Setup PM2 to start on system boot
pm2 startup systemd
# This outputs a sudo command - COPY AND RUN that command exactly as shown!
# Example output:
# sudo env PATH=$PATH:/home/ubuntu/.nvm/versions/node/v24.13.0/bin pm2 startup systemd -u ubuntu --hp /home/ubuntu

# Optional: Install PM2 log rotation
pm2 install pm2-logrotate

Per-App Node Versions: Use nvm use 20 before starting apps that need Node 20. PM2 will remember the Node version used when you save the process list.

6) Configure NGINX Reverse Proxy

A) Create Prerequisite Files First

These files must exist BEFORE creating the main NGINX config:

# 1. Create WebSocket upgrade map (required for WebSocket support)
sudo nano /etc/nginx/conf.d/connection_upgrade.conf

# Paste this content:
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

# 2. Create admin protection snippet (required by main config)
sudo mkdir -p /etc/nginx/snippets
sudo nano /etc/nginx/snippets/admin-tailscale-only.conf

# Paste this content:
allow {{tutorial.tailscaleip}};  # Your deploy laptop's Tailscale IP
deny all;

# 3. Create proxy snippet (DRY — reused in every location block)
sudo nano /etc/nginx/snippets/proxy_nuxt.conf

# Paste this content:
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $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_redirect off;
proxy_read_timeout 60s;

# 4. Create rate limit zones (one file, one place — don't duplicate in nginx.conf)
sudo nano /etc/nginx/conf.d/00-rate-limit.conf

# Paste this content:
limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=login:10m   rate=2r/s;

# 6. Create Let's Encrypt webroot directory
sudo mkdir -p /var/www/letsencrypt/.well-known/acme-challenge

# 7. Create application directory
sudo mkdir -p /var/www/{{tutorial.domain}}
sudo chown -R $USER:$USER /var/www/{{tutorial.domain}}

# 8. Create maintenance page directory
sudo mkdir -p /var/www/maintenance

B) Create HTTP-Only Config (Pre-SSL)

Start with HTTP only — Certbot needs this to validate your domain:

sudo nano /etc/nginx/sites-available/{{tutorial.domain}}

# === STAGE 1: HTTP-ONLY CONFIG (use until Certbot runs) ===

upstream nuxt_app {
  server 127.0.0.1:{{tutorial.appport}};
  keepalive 64;
}

server {
  listen 80;
  listen [::]:80;
  server_name {{tutorial.domain}} {{tutorial.domain2}};

  # Let's Encrypt validation (REQUIRED for Certbot)
  location ^~ /.well-known/acme-challenge/ {
    root /var/www/letsencrypt;
  }

  # Temporary: proxy to app (will become redirect after SSL)
  location / {
    proxy_pass http://nuxt_app;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $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;
  }
}

# Enable the site
sudo ln -s /etc/nginx/sites-available/{{tutorial.domain}} /etc/nginx/sites-enabled/

# Remove default site (optional)
sudo rm -f /etc/nginx/sites-enabled/default

# Test configuration - should pass now!
sudo nginx -t

# Reload NGINX
sudo systemctl reload nginx

# On the VPS — start a quick test server:
node -e "require('http').createServer((req,res)=>res.end('OK from {{tutorial.appport}}\\n')).listen({{tutorial.appport}},'127.0.0.1'); console.log('listening')"

# From your laptop — test directly (bypassing any CDN/proxy):
curl -v http://{{tutorial.ipaddress}} -H 'Host: {{tutorial.domain}}'
# Should return "OK from {{tutorial.appport}}"

# Stop the test server with Ctrl+C when done

# Edit hosts file
sudo nano /etc/hosts

# Add a line mapping your domain to the server IP:
{{tutorial.ipaddress}}  {{tutorial.domain}}  {{tutorial.domain2}}

# Save and exit (Ctrl+O, Enter, Ctrl+X in nano)

# Test - should now connect to your server
curl http://{{tutorial.domain}}
# Or open http://{{tutorial.domain}} in your browser

# 1. Open Notepad as Administrator:
#    - Press Win key, type "Notepad"
#    - Right-click → "Run as administrator"

# 2. In Notepad: File → Open, navigate to:
#    C:\Windows\System32\drivers\etc\hosts
#    (Change file filter from "*.txt" to "All Files")

# 3. Add a line at the bottom:
{{tutorial.ipaddress}}  {{tutorial.domain}}  {{tutorial.domain2}}

# 4. Save the file

# 5. Flush DNS cache (in Command Prompt as Admin):
ipconfig /flushdns

# On the VPS, if you don't know the public IP:
curl -4 ifconfig.me

# Or check network interface:
ip addr show eth0 | grep "inet " | awk '{print $2}' | cut -d/ -f1

C) Get SSL Certificate (Run Certbot Now)

With HTTP config working, get your SSL certificate:

# Install Certbot
sudo apt install -y certbot python3-certbot-nginx

# Get certificate (Certbot will modify your NGINX config)
sudo certbot --nginx -d {{tutorial.domain}} -d {{tutorial.domain2}}

# Follow prompts:
# - Enter email address
# - Agree to terms
# - Choose redirect option: Yes (redirect HTTP to HTTPS)

# Verify SSL works
sudo nginx -t
sudo systemctl reload nginx

D) Create Maintenance Page

Create a maintenance page before the full config — it's referenced by the error_page directive:

sudo nano /var/www/maintenance/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Maintenance</title>
  <style>
    body { font-family: system-ui, sans-serif; display: flex; justify-content: center;
           align-items: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
    .box { text-align: center; padding: 2rem; }
    h1 { color: #333; }
    p { color: #666; }
  </style>
</head>
<body>
  <div class="box">
    <h1>Under Maintenance</h1>
    <p>We'll be back shortly. Please try again in a few minutes.</p>
  </div>
</body>
</html>

E) Upgrade to Full Production Config (Post-SSL)

After Certbot succeeds, replace the entire file with the clean config including caching, security headers, and maintenance mode:

sudo nano /etc/nginx/sites-available/{{tutorial.domain}}

# === STAGE 2: FULL HTTPS CONFIG (after Certbot) ===
# Replace the ENTIRE file content with this clean config.

upstream nuxt_app {
  server 127.0.0.1:{{tutorial.appport}};
  keepalive 64;
}

# --- Maintenance mode toggle ---
# To enable maintenance: sudo touch /var/www/maintenance/enabled
# To disable:            sudo rm /var/www/maintenance/enabled

# HTTP -> HTTPS redirect (keep ACME for cert renewals)
server {
  listen 80;
  listen [::]:80;
  server_name {{tutorial.domain}} {{tutorial.domain2}};

  location ^~ /.well-known/acme-challenge/ {
    root /var/www/letsencrypt;
  }

  return 301 https://$host$request_uri;
}

# Main HTTPS server
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name {{tutorial.domain}};

  # SSL certs (adjust path if Certbot used a different name)
  ssl_certificate /etc/letsencrypt/live/{{tutorial.domain}}/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/{{tutorial.domain}}/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

  # Security headers (keep CSP in-app via Nuxt)
  add_header X-Frame-Options "SAMEORIGIN" always;
  add_header X-Content-Type-Options "nosniff" always;
  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
  add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;
  add_header X-XSS-Protection "0" always;

  # HSTS — avoid 'preload' until all subdomains are HTTPS forever
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

  # Root for static files (Nuxt .output/public)
  root /var/www/{{tutorial.domain}}/app/.output/public;

  # --- Maintenance mode: if /var/www/maintenance/enabled exists, show maintenance page ---
  error_page 503 @maintenance;
  location @maintenance {
    root /var/www/maintenance;
    try_files /index.html =503;
    internal;
  }
  set $maintenance 0;
  if (-f /var/www/maintenance/enabled) {
    set $maintenance 1;
  }

  # Protect /admin/analytics (VPN-only)
  location ^~ /admin/analytics {
    include /etc/nginx/snippets/admin-tailscale-only.conf;
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  # Nuxt build assets (content-hashed — cache forever)
  location ^~ /_nuxt/ {
    try_files $uri =404;
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    access_log off;
  }

  # Static assets (not always fingerprinted)
  location ~* \.(webp|jpg|jpeg|png|gif|ico|svg)$ {
    try_files $uri @app;
    expires 30d;
    add_header Cache-Control "public, max-age=2592000" always;
    access_log off;
  }
  location ~* \.(woff|woff2|ttf|eot|otf)$ {
    try_files $uri @app;
    expires 1y;
    add_header Cache-Control "public, max-age=31536000" always;
    access_log off;
  }
  location ~* \.(css|js)$ {
    try_files $uri @app;
    expires 7d;
    add_header Cache-Control "public, max-age=604800" always;
    access_log off;
  }

  # Fallback: proxy to Nuxt app
  location @app {
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  # Login/auth pages (stricter rate limit)
  location ~ ^/(login|auth) {
    if ($maintenance) { return 503; }
    limit_req zone=login burst=5 nodelay;
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  # Default: proxy everything else to Nuxt
  location / {
    if ($maintenance) { return 503; }
    limit_req zone=general burst=20 nodelay;
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;

    # If upstream is down and maintenance is NOT enabled, show 502
    error_page 502 504 =502 /50x-fallback.html;
  }

  # Health check (bypasses maintenance mode)
  location = /health {
    access_log off;
    return 200 "healthy\n";
    add_header Content-Type text/plain;
  }

  # Deny access to hidden files (.env, .git, etc.)
  location ~ /\. {
    deny all;
    access_log off;
    log_not_found off;
  }
}

# Redirect www -> non-www (only if using www subdomain)
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name {{tutorial.domain2}};

  ssl_certificate /etc/letsencrypt/live/{{tutorial.domain}}/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/{{tutorial.domain}}/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

  return 301 https://{{tutorial.domain}}$request_uri;
}

# Test and reload
sudo nginx -t
sudo systemctl reload nginx

Note: If Certbot created different SSL paths, check with sudo certbot certificates and adjust the paths in your config accordingly.

# Enable maintenance mode (shows maintenance page to all visitors):
sudo touch /var/www/maintenance/enabled
sudo systemctl reload nginx

# Disable maintenance mode (back to normal):
sudo rm /var/www/maintenance/enabled
sudo systemctl reload nginx

# Add the extra domain to your existing certificate:
sudo certbot --nginx -d {{tutorial.domain}} -d {{tutorial.domain2}}

# Or get a separate certificate:
sudo certbot --nginx -d {{tutorial.domain2}}

sudo nano /etc/nginx/sites-available/{{tutorial.domain2}}

# {{tutorial.domain2}} — proxies to the SAME Nuxt app as {{tutorial.domain}}
# The Nuxt app reads the Host header to switch branding.

server {
  listen 80;
  listen [::]:80;
  server_name {{tutorial.domain2}};

  location ^~ /.well-known/acme-challenge/ {
    root /var/www/letsencrypt;
  }

  return 301 https://{{tutorial.domain2}}$request_uri;
}

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name {{tutorial.domain2}};

  ssl_certificate /etc/letsencrypt/live/{{tutorial.domain2}}/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/{{tutorial.domain2}}/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

  # Same security headers
  add_header X-Frame-Options "SAMEORIGIN" always;
  add_header X-Content-Type-Options "nosniff" always;
  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
  add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;
  add_header X-XSS-Protection "0" always;
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

  # Same root — Nuxt build assets are shared
  root /var/www/{{tutorial.domain}}/app/.output/public;

  # Maintenance mode (same toggle file)
  error_page 503 @maintenance;
  location @maintenance {
    root /var/www/maintenance;
    try_files /index.html =503;
    internal;
  }
  set $maintenance 0;
  if (-f /var/www/maintenance/enabled) {
    set $maintenance 1;
  }

  # Same static asset caching
  location ^~ /_nuxt/ {
    try_files $uri =404;
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    access_log off;
  }

  location @app {
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  location ~ ^/(login|auth) {
    if ($maintenance) { return 503; }
    limit_req zone=login burst=5 nodelay;
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  location / {
    if ($maintenance) { return 503; }
    limit_req zone=general burst=20 nodelay;
    proxy_pass http://nuxt_app;
    include /etc/nginx/snippets/proxy_nuxt.conf;
  }

  location = /health {
    access_log off;
    return 200 "healthy\n";
    add_header Content-Type text/plain;
  }

  location ~ /\. {
    deny all;
    access_log off;
    log_not_found off;
  }
}

# Enable the site and reload
sudo ln -s /etc/nginx/sites-available/{{tutorial.domain2}} /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Edit main NGINX config
sudo nano /etc/nginx/nginx.conf

# Find and uncomment/add in the http { } block:

##
# Gzip Settings
##
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_min_length 256;
gzip_types
    application/atom+xml
    application/geo+json
    application/javascript
    application/json
    application/ld+json
    application/manifest+json
    application/rdf+xml
    application/rss+xml
    application/xhtml+xml
    application/xml
    font/eot
    font/otf
    font/ttf
    image/svg+xml
    text/css
    text/javascript
    text/plain
    text/xml;

# Add inside your server { listen 443 ssl ... } block:

# OCSP Stapling (faster SSL handshakes)
ssl_stapling on;
ssl_stapling_verify on;
resolver 1.1.1.1 8.8.8.8 valid=300s;
resolver_timeout 5s;

# Test configuration
sudo nginx -t

# Reload NGINX
sudo systemctl reload nginx

# Test gzip is working (look for "Content-Encoding: gzip")
curl -H "Accept-Encoding: gzip" -I https://{{tutorial.domain}}

# Add to http { } block in nginx.conf:
proxy_cache_path /tmp/cache-{{tutorial.appname}} levels=1:2 keys_zone=microcache:10m max_size=100m inactive=1h use_temp_path=off;

# Add to your site config, in specific location blocks:
location /api/ {
    # Cache for 1 second (microcache)
    proxy_cache microcache;
    proxy_cache_valid 200 1s;
    proxy_cache_use_stale updating;
    proxy_cache_background_update on;
    proxy_cache_lock on;

    # Show cache status in response header (for debugging)
    add_header X-Cache-Status $upstream_cache_status;

    proxy_pass http://nuxt_app;
    # ... other proxy settings
}

7) Deploy Nuxt Application

A) Create Secure Directory Structure

Create the directory structure that separates code from persistent data:

# Create shared directory for persistent files
# (app/ will be created by git clone or rsync in the next step)
sudo mkdir -p /var/www/{{tutorial.domain}}/shared
sudo mkdir -p /var/www/{{tutorial.domain}}/logs/archives

# Set ownership to your user (so you can deploy without sudo)
sudo chown -R $USER:$USER /var/www/{{tutorial.domain}}

# Lock shared/ directory — prevents other local users from listing its contents
chmod 700 /var/www/{{tutorial.domain}}/shared

# Verify structure and permissions
tree -apug --dirsfirst -L 2 /var/www/{{tutorial.domain}}

Your server will have this structure after deployment:

/var/www/{{tutorial.domain}}/
├── [drwxr-xr-x] app/                    # Created by git clone or rsync (Step B)
│   ├── .output/            # Nuxt build output
│   ├── prisma/
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── ecosystem.config.cjs
│   └── .env -> ../shared/.env   # Symlink (Step E)
├── [drwx------] shared/                 # chmod 700 — only your user can access
│   ├── [-rw-------] .env                # chmod 600 — secrets, NEVER in git
│   └── [-rw-------] db.sqlite           # chmod 600 — created by Prisma migrate
└── [drwxr-xr-x] logs/                   # PM2 logs (optional)
    └── archives/

# Should print "readable" / "writable" — if not, check ownership
test -r /var/www/{{tutorial.domain}}/shared/.env && echo ".env readable"
test -w /var/www/{{tutorial.domain}}/shared/db.sqlite && echo "db writable" || echo "db not yet created (normal before first migration)"

B) Upload or Clone Your Project

Option 1: Clone from Git (git was installed in Section 1)

# On the VPS, clone directly into the app/ directory:
cd /var/www/{{tutorial.domain}}
git clone https://github.com/yourusername/{{tutorial.appname}}.git app

# "app" at the end names the target directory (instead of the repo name)
# No chown needed — you own the parent directory (set in Step A),
# so app/ and all its contents are automatically owned by your user

Option 2: Upload deploy folder (recommended for pre-built apps)

your-project/
└── {{tutorial.deploydir}}/
    ├── .output/          # Nuxt build output
    ├── prisma/
    │   └── schema.prisma # Database schema (NO db.sqlite!)
    ├── package.json
    ├── pnpm-lock.yaml
    └── ecosystem.config.cjs

# Run these commands FROM YOUR LOCAL MACHINE (laptop/WSL2)
# First, cd to the PARENT folder of your deploy directory:
cd /path/to/your-project

# Using rsync (recommended - creates app/ directory automatically):
rsync -avz --progress {{tutorial.deploydir}}/ {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:/var/www/{{tutorial.domain}}/app/

# Or using scp (need to create app/ directory first on server):
ssh {{tutorial.sudouser}}@{{tutorial.tsHostname()}} "mkdir -p /var/www/{{tutorial.domain}}/app"
scp -r {{tutorial.deploydir}}/* {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:/var/www/{{tutorial.domain}}/app/

C) Required Files in Deploy Folder

Ensure these files/folders are present in your deploy:

• .output/ - Nuxt production build
• package.json - Dependencies manifest
• pnpm-lock.yaml - Locked dependency versions
• ecosystem.config.cjs - PM2 configuration
• prisma/schema.prisma - Database schema
• scripts/ - Preflight and utility scripts (optional)

D) Configure Environment (in shared/)

# Create .env in shared directory (NOT in app directory!)
nano /var/www/{{tutorial.domain}}/shared/.env

Example production .env:

# Database (points to shared directory)
DATABASE_URL="file:/var/www/{{tutorial.domain}}/shared/db.sqlite"

# Session (generate with: openssl rand -hex 32)
NUXT_SESSION_PASSWORD="your-64-character-hex-password-here"

# Production URL
NUXT_PUBLIC_SITE_URL="https://{{tutorial.domain}}"

# Node environment
NODE_ENV="production"

# Optional: OAuth providers
# NUXT_OAUTH_GITHUB_CLIENT_ID="..."
# NUXT_OAUTH_GITHUB_CLIENT_SECRET="..."

# Lock down permissions (owner read/write only)
chmod 700 /var/www/{{tutorial.domain}}/shared
chmod 600 /var/www/{{tutorial.domain}}/shared/.env
# db.sqlite will be locked after first migration (Step 8B)

E) Create Symlink for .env

Link the shared .env to your app directory so the app can find it:

# Create symlink from app to shared .env
ln -sf /var/www/{{tutorial.domain}}/shared/.env /var/www/{{tutorial.domain}}/app/.env

# Verify symlink
ls -la /var/www/{{tutorial.domain}}/app/.env
# Should show: .env -> /var/www/{{tutorial.domain}}/shared/.env

# Create a keys directory for all your project secrets
# Windows:
C:\keys\
├── {{tutorial.appname}}\
│   └── .env           # Dev/staging secrets for this project
├── another-project\
│   └── .env
└── ssh\               # Optional: backup of SSH keys

# Linux/macOS:
~/keys/
├── {{tutorial.appname}}/
│   └── .env
└── another-project/
    └── .env

# Option 1: Use --dotenv flag with pnpm/npm
pnpm dev --dotenv C:/keys/{{tutorial.appname}}/.env         # Windows
pnpm dev --dotenv ~/keys/{{tutorial.appname}}/.env          # Linux/Mac

# Option 2: Set in package.json scripts
"scripts": {
  "dev": "nuxt dev --dotenv ../keys/.env",
  "dev:local": "nuxt dev --dotenv C:/keys/{{tutorial.appname}}/.env"
}

# Option 3: Symlink (Linux/Mac only)
ln -s ~/keys/{{tutorial.appname}}/.env .env

8) Install Dependencies and Setup Database

A) Install Production Dependencies

# Navigate to app directory
cd /var/www/{{tutorial.domain}}/app

# Ensure correct Node version is active
nvm use 24

# Install dependencies (frozen lockfile for reproducibility)
pnpm install --frozen-lockfile

# Or for production-only dependencies:
# pnpm install --prod --frozen-lockfile

B) Setup Prisma and Database

# Generate Prisma Client
pnpm dlx prisma generate

# Run database migrations (creates db.sqlite in shared/ via DATABASE_URL)
pnpm dlx prisma migrate deploy

# Optional: Seed database with initial data
pnpm db:seed

# Verify database connectivity
pnpm run preflight:db

# Verify database was created in shared directory
ls -la /var/www/{{tutorial.domain}}/shared/db.sqlite

# Lock down database file (owner read/write only)
chmod 600 /var/www/{{tutorial.domain}}/shared/db.sqlite

C) Build Application (if not pre-built)

# If you cloned from Git and need to build:
pnpm build

# Verify build succeeded
ls -lh .output/server/index.mjs

D) Run Preflight Checks

# Verify runtime dependencies
pnpm run preflight

# Check database connectivity
pnpm run preflight:db

# Both should complete without errors

9) Start Application with PM2

A) Initial Start

# Navigate to app directory
cd /var/www/{{tutorial.domain}}/app

# Ensure correct Node version
nvm use 24

# Delete existing PM2 process if it exists
pm2 delete {{tutorial.appname}} || true

# Start application using ecosystem config
pm2 start ecosystem.config.cjs --env production

# Save PM2 process list (survives reboots)
pm2 save

# View logs
pm2 logs {{tutorial.appname}} --lines 200

B) Verify Application is Running

# Check PM2 status
pm2 list

# Test application locally
curl -i http://127.0.0.1:{{tutorial.appport}}/

# Should return 200 OK with HTML content

# Monitor application
pm2 monit

C) PM2 Management Commands

# Reload app after code changes (zero-downtime)
pm2 reload ecosystem.config.cjs --env production --update-env

# Restart app (brief downtime)
pm2 restart {{tutorial.appname}}

# Stop app
pm2 stop {{tutorial.appname}}

# View real-time logs
pm2 logs {{tutorial.appname}} --lines 100

# Clear logs
pm2 flush

# Application info
pm2 info {{tutorial.appname}}

Multiple Node Versions: If running multiple apps with different Node versions: nvm use 20 && pm2 start app1.js , then nvm use 24 && pm2 start app2.js . PM2 remembers which Node binary to use for each app.

# Upload the script to your VPS (from your laptop):
scp setup-release-dirs.sh {{tutorial.sudouser}}@{{tutorial.tsHostname()}}:~/

# On the VPS — run it:
chmod +x ~/setup-release-dirs.sh
./setup-release-dirs.sh {{tutorial.domain}} {{tutorial.sudouser}}

/var/www/{{tutorial.domain}}/
├── releases/                    # Versioned releases
│   ├── 20260125_143052_abc123/  # Timestamp + commit hash
│   ├── 20260124_092130_def456/
│   └── 20260123_181500_ghi789/
├── current -> releases/20260125.../  # Symlink to active release
├── [drwx------] shared/              # chmod 700 — only deploy user
│   ├── [-rw-------] .env             # chmod 600 — secrets
│   ├── [-rw-------] db.sqlite        # chmod 600 — database
│   └── images/                       # User uploads (if any)
└── logs/                             # Persistent logs
    ├── err.log
    ├── out.log
    └── archives/                     # Per-release log archives

# Create release directories
sudo mkdir -p /var/www/{{tutorial.domain}}/releases
sudo mkdir -p /var/www/{{tutorial.domain}}/shared
sudo mkdir -p /var/www/{{tutorial.domain}}/logs/archives

# Set ownership and lock down shared/
sudo chown -R $USER:$USER /var/www/{{tutorial.domain}}
chmod 700 /var/www/{{tutorial.domain}}/shared

# Migrate from simple app/ structure (if upgrading)
# mv /var/www/{{tutorial.domain}}/app /var/www/{{tutorial.domain}}/releases/initial
# ln -sfn /var/www/{{tutorial.domain}}/releases/initial /var/www/{{tutorial.domain}}/current

#!/bin/bash
# deploy.sh - Run from CI/CD or locally
set -e

DOMAIN="{{tutorial.domain}}"
BASE_DIR="/var/www/$DOMAIN"
RELEASE_ID="$(date +%Y%m%d_%H%M%S)_$(git rev-parse --short HEAD)"
RELEASE_DIR="$BASE_DIR/releases/$RELEASE_ID"

echo "Deploying release: $RELEASE_ID"

# 1. Create release directory
mkdir -p "$RELEASE_DIR"

# 2. Copy/upload application files (adjust for your setup)
rsync -avz --exclude='.env' --exclude='node_modules' ./ "$RELEASE_DIR/"

# 3. Link shared resources
ln -sfn "$BASE_DIR/shared/.env" "$RELEASE_DIR/.env"
ln -sfn "$BASE_DIR/shared/db.sqlite" "$RELEASE_DIR/prisma/db.sqlite"
# ln -sfn "$BASE_DIR/shared/images" "$RELEASE_DIR/.data/images"  # If using uploads

# 4. Install dependencies
cd "$RELEASE_DIR"
pnpm install --frozen-lockfile --prod

# 5. Generate Prisma client
pnpm dlx prisma generate

# 6. Run migrations (if any)
pnpm dlx prisma migrate deploy

# 6b. Lock db.sqlite after first migration creates it
chmod 600 "$BASE_DIR/shared/db.sqlite" 2>/dev/null || true

# 7. Archive current logs (before switching)
if [ -L "$BASE_DIR/current" ]; then
  PREV_RELEASE=$(basename $(readlink "$BASE_DIR/current"))
  mkdir -p "$BASE_DIR/logs/archives/$PREV_RELEASE"
  cp "$BASE_DIR/logs"/*.log "$BASE_DIR/logs/archives/$PREV_RELEASE/" 2>/dev/null || true
fi

# 8. Switch symlink (atomic operation = zero downtime)
ln -sfn "$RELEASE_DIR" "$BASE_DIR/current"

# 9. Reload PM2 (zero-downtime with cluster mode)
pm2 reload ecosystem.config.cjs --update-env

# 10. Health check
sleep 3
curl -sf http://127.0.0.1:{{tutorial.appport}}/health || echo "Warning: Health check failed"

# 11. Cleanup old releases (keep last 5)
cd "$BASE_DIR/releases"
ls -t | tail -n +6 | xargs -r rm -rf

echo "✅ Deployed: $RELEASE_ID"

# List available releases
ls -la /var/www/{{tutorial.domain}}/releases/

# Rollback to previous release
PREV_RELEASE=$(ls -t /var/www/{{tutorial.domain}}/releases/ | sed -n '2p')
ln -sfn /var/www/{{tutorial.domain}}/releases/$PREV_RELEASE /var/www/{{tutorial.domain}}/current
pm2 reload ecosystem.config.cjs --update-env

# Verify rollback
readlink /var/www/{{tutorial.domain}}/current

# After updating NGINX config:
sudo nginx -t && sudo systemctl reload nginx

# After updating ecosystem.config.cjs:
cd /var/www/{{tutorial.domain}}/current
pm2 delete {{tutorial.appname}} || true
pm2 start ecosystem.config.cjs --env production
pm2 save

// For zero-downtime reloads, use cluster mode
// cwd points to the current symlink — PM2 follows it on reload
module.exports = {
  apps: [{
    name: "{{tutorial.appname}}",
    cwd: "/var/www/{{tutorial.domain}}/current",
    script: ".output/server/index.mjs",
    instances: 2,                    // Cluster mode (2+ instances)
    exec_mode: "cluster",
    env_production: {
      NODE_ENV: "production",
      PORT: {{tutorial.appport}}
    },
    // Use absolute paths for logs (outside releases)
    error_file: "/var/www/{{tutorial.domain}}/logs/err.log",
    out_file: "/var/www/{{tutorial.domain}}/logs/out.log",
    log_date_format: "YYYY-MM-DD HH:mm:ss Z",
    merge_logs: true
  }]
};

Additional Resources

• Nuxt 4 Documentation
• Prisma Documentation
• PM2 Documentation
• NGINX Documentation
• NVM Documentation
• Docker Documentation
• Certbot Documentation
• Ubuntu Server Guide