IMS Publishing Runbook

Document ID: OPS-PUB-001 Status: Active Owner: Paul (Infrastructure) Last Edited: Claude, 2026-02-24 Review Due: 2026-05-24

---

Architecture Overview

GitHub (coown-box/Tech-Pub)          ← SINGLE SOURCE OF TRUTH
  └── main branch (released)
           │
     ┌─────┴──────────────────────────────────────┐
     │                                            │
VPS-CPU (89.167.53.57)                    VPS-HUB (46.225.188.41)
Outline — outline.coown.foundation        MkDocs — docs.coown.foundation
Team internal wiki                        External / regulatory publication

Layer	URL	Audience	Auth	Rebuild trigger
GitHub	github.com/coown-box/Tech-Pub	Team (edit)	GitHub access	—
Outline	outline.coown.foundation	Team (browse + edit)	Google OAuth	Manual / future webhook
MkDocs	docs.coown.foundation	External (read-only)	None	Cron every 15 min

---

Edit Paths

Path A — Local machine → GitHub

# 1. Pull latest
git -C ~/code/docs/Tech-Pub pull origin main

# 2. Edit files in ~/code/docs/Tech-Pub/docs/IMS/...

# 3. Commit and push
git -C ~/code/docs/Tech-Pub add <file>
git -C ~/code/docs/Tech-Pub commit -m "docs(<domain>): <change description>"
git -C ~/code/docs/Tech-Pub push origin main

# 4. MkDocs auto-rebuilds within 15 minutes (cron on VPS-HUB)

Path B — Outline UI → GitHub (future)

Currently Outline is in read-mode (browse only). Edit-back to GitHub requires the Outline GitHub App integration — see Pending Setup.

---

Release Promotion Workflow

MkDocs at docs.coown.foundation always serves the main branch. Any merge to main is automatically published within 15 minutes.

Standard release (merge to main)

# Option 1: Direct push to main (team members with access)
git -C ~/code/docs/Tech-Pub push origin main

# Option 2: PR workflow (draft → review → merge)
git -C ~/code/docs/Tech-Pub checkout -b draft/your-change
# ... edit ...
git push origin draft/your-change
# Open PR on GitHub → review → merge to main

Versioned release (for regulatory submissions)

# Tag a specific release for long-term reference
git -C ~/code/docs/Tech-Pub tag -a v2026-02-24 -m "IMS release 2026-02-24"
git -C ~/code/docs/Tech-Pub push origin v2026-02-24

# The tag is immutable — use the tagged URL as a durable reference:
# https://github.com/coown-box/Tech-Pub/tree/v2026-02-24

Note: docs.coown.foundation always serves main (latest released). For a point-in-time snapshot to send to authorities, share the GitHub tag URL.

---

Manual Rebuild

Trigger MkDocs rebuild immediately

ssh cwn-hub "sudo /opt/rebuild-docs.sh"
# Check log:
ssh cwn-hub "tail -10 /var/log/docs-rebuild.log"

Check rebuild status

# Last rebuild timestamp and result
ssh cwn-hub "grep 'Rebuild complete\|fatal\|ERROR' /var/log/docs-rebuild.log | tail -5"

---

Emergency Recovery

MkDocs site down

# 1. SSH to VPS-HUB
ssh cwn-hub

# 2. Check nginx
sudo systemctl status nginx
sudo nginx -t  # test config

# 3. Check web root has content
ls /var/www/docs.coown.foundation/ | head -5

# 4. Force rebuild
sudo /opt/rebuild-docs.sh

# 5. If git pull fails (token expired), update the remote URL:
cd /opt/tech-pub
# Get new token from: gh auth token (on local machine)
git remote set-url origin 'https://Managed-Trust:<TOKEN>@github.com/coown-box/Tech-Pub.git'
sudo /opt/rebuild-docs.sh

Outline down

# 1. SSH to VPS-CPU
ssh cwn-cpu

# 2. Check container
sudo docker ps | grep outline
sudo docker logs outline-cpu 2>&1 | tail -20

# 3. Restart
sudo bash -c 'cd /data/coolify/services/outline-cpu && docker compose --env-file .env up -d outline'

# 4. Check nginx on VPS-HUB (outline proxied through HUB)
ssh cwn-hub "sudo nginx -t && sudo systemctl reload nginx"

Full recovery from scratch

# MkDocs: clone repo and rebuild
ssh cwn-hub
git clone https://Managed-Trust:<TOKEN>@github.com/coown-box/Tech-Pub.git /opt/tech-pub
mkdocs build --config-file /opt/tech-pub/mkdocs.yml -d /var/www/docs.coown.foundation/

---

Pending Setup

Outline content sync (GitHub → Outline)

Outline does not yet auto-import documents from GitHub. To populate Outline with IMS content:

1. Simon logs in to outline.coown.foundation with Google account
2. In Outline Settings → API → create an API token
3. Add token as GitHub secret OUTLINE_API_TOKEN in Tech-Pub repo
4. A GitHub Actions workflow can then push documents to Outline via the API on each push to main

Outline edit-back (Outline → GitHub)

The Outline GitHub App integration (write-back path) requires a GitHub App with contents: write on the Tech-Pub repo. This is a future setup item — see Dev-Ops/projects/ims-restructuring/SETUP-REMAINING.md.

GitHub Actions deploy (faster than cron)

Add VPS_DEPLOY_KEY secret to Tech-Pub repo settings to enable sub-minute deploys on push. The cron (15 min) remains as fallback.

---

Health Monitoring

GitHub Actions health check runs every 30 minutes. If either docs.coown.foundation or outline.coown.foundation is unreachable, a GitHub issue is created in coown-box/Tech-Pub with the label health-check-alert.

Check: https://github.com/coown-box/Tech-Pub/issues?q=label%3Ahealth-check-alert

---

Key File Locations

File	Purpose
/opt/tech-pub/	Tech-Pub clone on VPS-HUB
/opt/rebuild-docs.sh	Rebuild script on VPS-HUB
/etc/cron.d/docs-rebuild	Cron schedule (every 15 min)
/var/www/docs.coown.foundation/	Built MkDocs site
/var/log/docs-rebuild.log	Rebuild log
/data/coolify/services/outline-cpu/.env	Outline configuration on VPS-CPU
~/code/docs/Tech-Pub/mkdocs.yml	MkDocs config (in GitHub repo)