# SohoPHP Node.js CI/CD Toolkit

Location on this VPS: /usr/local/share/sohophp/node-cicd

Public docs site: https://docs.v4.sohophp.app

This directory contains the Node.js multi-version deployment toolkit built on this Rocky/EL9 host for SohoPHP-style hosting.

It is designed so you can:

• inspect what was installed
• understand how it works
• reuse the same layout on another VPS
• copy the scripts/templates as a bundle
• onboard new Node sites with the same conventions used here
• browse the exported docs from a web UI at docs.v4.sohophp.app
• refresh the docs site with one command via publish-docs-site
• roll a site back to a previous release via rollback-node-release

---

# What this toolkit provides

# Runtime model

• Nginx handles public HTTP/HTTPS
• Node app listens on 127.0.0.1:<port>
• systemd manages the Node process
• fnm selects the requested Node version for build/run
• release layout uses:
• current
• releases/
• shared/
• shared env is loaded from .env / .env.local
• cicd may deploy through a limited sudoers policy
• bootstrap-node-site can create a brand-new starter repo + site scaffold + first deploy in one command
• docs.v4.sohophp.app exposes the exported toolkit docs and bundle downloads over HTTPS
• publish-docs-site syncs docs content, rebuilds artifacts, verifies the bundle, and republishes the docs site
• rollback-node-release switches current back to an older release, restarts the service, and verifies health

# Supported Node versions on this VPS

Installed under the git user with fnm:

• Node 18.20.8
• Node 20.20.2
• Node 22.22.3

fnm home:

• /home/git/.local/share/fnm

---

# Current status

# Already implemented and verified

• multi-version Node hosting for 18 / 20 / 22
• release-layout deploys with deploy-node-release
• CI wrapper deploys with cicd-deploy-node-site
• shared env initialization with init-node-shared-env
• one-command new-site bootstrap with bootstrap-node-site
• HTTPS docs site serving exported toolkit docs
• one-command docs republish with publish-docs-site
• rollback to previous release with rollback-node-release
• real validation on:
• node.v4.sohophp.app
• node20.v4.sohophp.app
• docs.v4.sohophp.app

# Next planned CI/CD work

• GitHub Actions / Gitea Actions workflow examples
• webhook-triggered deploy flow
• release retention / old release cleanup
• deploy notifications
• database migration hook support
• optional automatic rollback policy on deploy failure

---

# Quick start on this VPS

# Browse docs in browser

• https://docs.v4.sohophp.app
• https://docs.v4.sohophp.app/doc/README.md
• https://docs.v4.sohophp.app/download/node-cicd-toolkit.tar.gz

# Refresh docs site after toolkit doc changes

sudo /usr/local/bin/publish-docs-site

If you only want to republish without creating a new docs repo commit:

sudo /usr/local/bin/publish-docs-site --skip-commit

# Roll back a site to the previous release

sudo /usr/local/bin/rollback-node-release --domain app.example.com

# Fastest path: bootstrap a new site

sudo /usr/local/bin/bootstrap-node-site \


  --domain example.com \


  --node-version 22 \


  --issue-cert \


  --email ops@example.com

# Manual path: create + env + deploy

sudo /usr/local/bin/create-node-site \


  --domain example.com \


  --node-version 22 \


  --issue-cert \


  --email ops@example.com





sudo /usr/local/bin/init-node-shared-env \


  --domain example.com \


  --file .env.local \


  --set APP_SECRET=*** \


  --set DATABASE_URL=change-me





sudo /usr/local/bin/cicd-deploy-node-site \


  --domain example.com

# Validate

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


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


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

---

# Suggested reading order

1. docs/01-overview-and-architecture.md
2. docs/02-script-reference.md
3. docs/03-how-to-add-a-new-site.md
4. docs/04-cicd-and-sudoers.md
5. docs/05-migrate-to-another-vps.md
6. docs/06-test-site-node.v4.sohophp.app.md
7. docs/09-test-site-node20.v4.sohophp.app.md
8. docs/10-docs-site-docs.v4.sohophp.app.md
9. docs/11-docs-auto-publish-publish-docs-site.md
10. docs/12-cicd-status-and-roadmap.md
11. docs/08-fast-migration-checklist.md

---

# Bundle export

A reusable tarball for migration is generated under:

• artifacts/node-cicd-toolkit.tar.gz
• artifacts/node-cicd-toolkit.sha256

Use these to copy the toolkit to another VPS, then follow the migration doc.