Runbook — Deploy Docusaurus

Complete deployment workflow for Docusaurus from Vera to VM700.

Deployment Architecture

Vera (source + build)
    ↓
npm run build → build/ (static HTML)
    ↓
rsync via Proxmox relay
    ↓
VM700 /opt/stacks/echohuman-docsaurus/site-build/
    ↓
nginx serves static files on port 7030
    ↓
CT101 Caddy routes public HTTPS
    ↓
https://docsaurus.echohuman.org

Prerequisites

• WireGuard connected (Vera → Helsinki2)
• SSH access to Proxmox host and VM700
• Docusaurus source on Vera: /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman/
• Node.js installed on Vera

Step 1 — Build on Vera

cd /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman
npm run build

Confirm output:

[SUCCESS] Generated static files in "build".

Step 2 — Relay Build to Proxmox

From Proxmox host ([email protected]):

rsync -avz --delete \
  [email protected]:'/home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman/build/' \
  /tmp/docsaurus-build/

Step 3 — Deploy to VM700

From Proxmox host:

rsync -avz --delete \
  /tmp/docsaurus-build/ \
  [email protected]:/opt/stacks/echohuman-docsaurus/site-build/

Do not copy node_modules to VM700. Only static build/ output.

Step 4 — Verify Deployment

From Proxmox host or Vera:

# Local check on VM700
ssh [email protected] "curl -sI http://localhost:7030 | head -3"

# Public check (may timeout on Proxmox due to pipe issues)
curl -I https://docsaurus.echohuman.org

Expected response:

HTTP/1.1 200 OK
Server: nginx/1.29.8
Content-Type: text/html

Step 5 — Verify Content

Check that new pages are accessible:

ssh [email protected] "ls /opt/stacks/echohuman-docsaurus/site-build/ | head -20"

Should show directories like: overview/, helsinki2/, vm700/, vera/, services/, repos/, cloudflare/, reports/, runbooks/

Troubleshooting

Issue	Cause	Fix
Build fails on Vera	Missing dependencies	npm install on Vera
rsync fails	SSH key issue	Verify SSH access to Proxmox and VM700
Old content still served	Browser cache	Hard refresh (Ctrl+Shift+R) or test with curl
404 on new pages	rsync didn't complete	Re-run rsync commands

Notes

• No container restart needed — nginx serves static files directly
• Build output is immutable — safe to deploy multiple times
• site-build/ directory is bind-mounted read-only in nginx container
• Cloudflare may cache old content — use Cache-Control: no-cache header or wait for TTL

Rollback

If deployment breaks the site:

1. Restore previous site-build/ from backup (if available)
2. Or rebuild and redeploy from Vera
3. Or revert Vera source to previous commit and rebuild

cd /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman
git log --oneline -5
git checkout <previous-commit>
npm run build
# Then re-deploy