# 03. How to Add a New Node Site

This is the operational procedure to add a new Node site on the current VPS.

# Fastest path: bootstrap everything at once

For a brand-new site with a minimal starter app, use:

sudo bootstrap-node-site \


  --domain app.example.com \


  --node-version 22 \


  --issue-cert \


  --email ops@example.com

This will:

• create /srv/git/app.example.com
• generate a minimal Node HTTP app skeleton
• generate package-lock.json
• initialize a git repo on main
• create the site scaffold via create-node-site
• seed shared/.env.local
• perform the first deploy

Use this when you want a new site to become reachable quickly and consistently.

# Manual path

# Prerequisites

• domain DNS points to this VPS
• Nginx is installed and running
• fnm + Node versions are installed for the git user
• git, cicd, webread model is already in place

# Step 1: Prepare the source repo

Recommended path:

sudo mkdir -p /srv/git


sudo chown git:git /srv/git


sudo -u git git clone <repo-url> /srv/git/<domain>

Or copy an existing local repo into:

• /srv/git/<domain>

# Step 2: Create the site scaffold

Example for Node22:

sudo create-node-site \


  --domain app.example.com \


  --node-version 22 \


  --issue-cert \


  --email ops@example.com

If you want to pin a specific port:

sudo create-node-site \


  --domain app.example.com \


  --node-version 22 \


  --port 22105

# Step 3: Initialize shared env

sudo init-node-shared-env \


  --domain app.example.com \


  --file .env.local \


  --set APP_SECRET=*** \


  --set DATABASE_URL=change-me

# Step 4: First deploy

sudo cicd-deploy-node-site --domain app.example.com

# Step 5: Validate

sudo systemctl status node-site@app.example.com.service --no-pager


curl -fsS http://127.0.0.1:<port>/healthz


curl -fsS https://app.example.com/healthz

# Step 6: Ongoing deploys

After pushing code updates to the repo path or updating the repo checkout, redeploy with:

sudo cicd-deploy-node-site --domain app.example.com

# Step 7: Optional release cleanup

After a successful deploy, prune older releases and keep only the newest N:

sudo cleanup-node-releases --domain app.example.com --keep 5 --prune

# Notes about build/runtime env

Both build and runtime load:

• .env
• .env.local

If your framework needs additional env files, either:

• extend the wrapper scripts, or
• make the framework load them itself

# Rollback approach

Rollback is now built in:

sudo rollback-node-release --domain app.example.com

To target a specific release:

sudo rollback-node-release --domain app.example.com --release 20260602151802