# 02. Script Reference

This document explains each script installed on the VPS.

# /usr/local/bin/bootstrap-node-site

# Purpose

One-command bootstrap for a brand-new Node site.

# Behavior

• creates /srv/git/<domain> if missing
• writes a minimal Node app skeleton
• generates package-lock.json
• initializes git on main
• calls create-node-site
• seeds shared/.env.local
• performs the first deployment through cicd-deploy-node-site

# Good use case

Use this for a fresh domain when you want a working starter site immediately.

# Example

sudo bootstrap-node-site \


  --domain node20.v4.sohophp.app \


  --node-version 20 \


  --site-greeting hello-from-bootstrap-node20 \


  --app-url http://node20.v4.sohophp.app

---

# /usr/local/bin/create-node-site

# Purpose

Create the base infrastructure for a Node site.

# Responsibilities

• choose/create site root
• choose/create log paths
• write /etc/node-sites/<domain>.env
• write Nginx vhost
• create release layout if enabled
• set SELinux directory and port context
• enable the site service template
• optionally issue Let's Encrypt certs

# Key options

• --domain DOMAIN
• --node-version 18|20|22
• --port PORT
• --issue-cert
• --cert-name NAME
• --email EMAIL
• --force
• --release-layout|--no-release-layout
• --run-user USER
• --start-command CMD
• --node-env ENV

# Example

sudo create-node-site --domain app.example.com --node-version 22 --port 22101

---

# /usr/local/bin/node-with-fnm

# Purpose

Stable wrapper to execute a shell command with a chosen Node version via fnm.

# Why it exists

systemd, sudo, and non-interactive shells are often unreliable if you assume fnm is already in PATH.

This wrapper makes the fnm path explicit.

# Example

sudo /usr/local/bin/node-with-fnm --user git --version 22 --shell-command 'node -v && npm -v'

---

# /usr/local/bin/node-site-runner

# Purpose

Runtime entrypoint for systemd services.

# Behavior

• reads /etc/node-sites/<domain>.env
• changes into the current release dir
• loads .env and .env.local if present
• exports HOST, PORT, NODE_ENV
• runs the start command through fnm

# Important note

This means your app can access values provided by shared env files without custom systemd drop-ins.

---

# /usr/local/bin/deploy-node-release

# Purpose

Deploy a new release from a repo/source tree.

# Behavior

• optionally fetch/checkout git ref
• copy source into a timestamped release
• set ownership/ACLs
• re-create shared symlinks
• run install/build commands with the requested Node version
• switch current
• restart service
• run healthcheck

# Important options

• --site-root
• --repo
• --ref
• --node-version
• --service
• --install-cmd
• --build-cmd
• --shared-link
• --healthcheck-url
• --healthcheck-expect
• --healthcheck-insecure

# Example

sudo deploy-node-release \


  --site-root /var/www/node22/app.example.com \


  --repo /srv/git/app.example.com \


  --ref main \


  --node-version 22 \


  --service node-site@app.example.com.service \


  --shared-link .env.local \


  --healthcheck-url http://127.0.0.1:22101/healthz \


  --healthcheck-expect '"ok": true'

---

# /usr/local/bin/rollback-node-release

# Purpose

Roll a site back to an older release already present under releases/.

# Behavior

• reads /etc/node-sites/<domain>.env
• chooses the latest non-current release by default
• can target a specific release path or timestamp
• rewires current
• restarts node-site@<domain>.service
• runs healthcheck
• automatically restores the previous current if rollback healthcheck fails

# Important options

• --domain DOMAIN
• --release TIMESTAMP_OR_PATH
• --previous
• --healthcheck-path /healthz
• --healthcheck-expect TEXT
• --healthcheck-insecure

# Example

sudo rollback-node-release --domain docs.v4.sohophp.app

---

# /usr/local/bin/init-node-shared-env

# Purpose

Initialize a shared env file inside the site's shared/ tree.

# Default output

Typically creates:

• shared/.env.local

# Example

sudo init-node-shared-env \


  --domain app.example.com \


  --file .env.local \


  --set APP_SECRET=change-me

---

# /usr/local/bin/cicd-deploy-node-site

# Purpose

Convenience wrapper for CI/CD.

# Behavior

• reads /etc/node-sites/<domain>.env
• derives SITE_ROOT, NODE_VERSION, PORT
• uses repo /srv/git/<domain> by default
• calls deploy-node-release
• points healthcheck to http://127.0.0.1:<PORT>/healthz by default

# Example

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

This is the preferred command for CI pipelines on this VPS.