Runbook — Rebuild and publish the docs portal

Use when: you committed a doc change and want it visible at admin.joaoluisbrazao.cloud/docs/.

Automatic path (preferred)

A cron rebuilds and publishes every hour. Just push to Forgejo and wait up to an hour.

cd /opt/infrastructure-docs
git add -A
git commit -m "docs: <what changed>"
git push origin main
# Wait up to 60 minutes, or trigger manually below.

Manual trigger

bash /opt/infrastructure-docs/scripts/rebuild.sh

The script: 1. git pull to fetch the latest commit 2. Runs mkdocs build via the squidfunk/mkdocs-material Docker image 3. Atomically swaps the published site/ to /opt/downrabbithole/html/docs/ 4. Logs result to /var/log/jb/docs-rebuild.log

No nginx reload is required — the files are served from a volume-mounted directory.

Troubleshooting

mkdocs build fails

Read the error in the script output. Most common: - Missing internal link → fix the link in the offending .md - YAML syntax error in mkdocs.yml → revalidate locally with mkdocs serve

Site shows stale content

Check the rebuild log:

tail -50 /var/log/jb/docs-rebuild.log

Manual rebuild:

bash /opt/infrastructure-docs/scripts/rebuild.sh

git pull fails

Likely a merge conflict. Resolve by:

cd /opt/infrastructure-docs
git status
git stash    # if local changes exist
git pull
git stash pop

Cron schedule

Defined in /etc/cron.d/jb-docs-rebuild:

*/60 * * * * root bash /opt/infrastructure-docs/scripts/rebuild.sh >> /var/log/jb/docs-rebuild.log 2>&1

Every 60 minutes is a deliberate trade-off: low resource cost, acceptable freshness for documentation. For instant publication after a push, use the manual trigger.

Forgejo webhook (future)

Tracked as a follow-up — Forgejo can POST to a local endpoint that triggers rebuild.sh immediately on push. Until then, hourly cron is the source of freshness.