Coaching operations documentation¶
Welcome. This site is the single place for production operations: scheduled jobs (systemd), reverse proxy (nginx), process manager (PM2 + Node.js), deploy permissions, and hosting docs.diasantos.com itself.
The application UI lives elsewhere; here we document servers, timers, and plumbing.
Documentation map¶
- Systemd cron
Timer coaching-cron-tick → POST /api/cron/tick, env file, sudo during deploy.
- Nginx
Reverse proxy for the Next.js app and TLS; long timeouts for admin deploy (SSE).
- Hosting this site
Serve documentation/site/ from docs.diasantos.com with Certbot.
- Deploy user & permissions
Unix user coaching, sudoers for cron install, MkDocs build, Node version.
- PM2 & systemd
PATH, nvm, interpreter in ecosystem — PM2 under systemd without surprises.
Stack overview (production)¶
┌─────────────────┐
Internet ───────►│ nginx (TLS) │
│ app + docs │
└────────┬────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Next.js │ │ Static MkDocs │ │ systemd timer │
│ pm2 :3000 │ │ site/ │ │ → /api/cron/* │
└────────────┘ └──────────────┘ └─────────────────┘
│
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘
Prefer the deployment overview
Start with Deployment — overview for a ordered checklist and links to every guide.
Edit or build locally¶
From the repository root:
cd documentation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve
Open http://127.0.0.1:8000 (English). Use the language switcher in the header for Português (/pt/).
Production build¶
cd documentation
pip install -r requirements.txt
mkdocs build
Output: documentation/site/. The admin Deploy pipeline runs documentation/build-from-deploy.sh on the server.
Repository¶
Source Markdown lives under documentation/docs/ in the coaching_v2 repository — use Edit this page in the footer when you're browsing a topic.