VPS Runbook¶
This page documents the normal live VPS workflow for Magikal.
Main paths¶
| Area | Path |
|---|---|
| Discord bot | /home/magikalbot/magikal-bot |
| Web panel | /home/magikalbot/magikal-panel |
| Documentation | /home/magikalbot/magikal-docs |
| Bot environment file | /etc/magikal-bot.env |
| Bot backups | /home/magikalbot/backups |
Linux users¶
| User | Purpose |
|---|---|
magikalbot |
Normal project editing, Git commits, VS Code Remote SSH work |
root / sudo |
Service restarts, system logs, Nginx, systemd, server-level changes |
Main services¶
| Service | Purpose |
|---|---|
magikal-bot |
Live Discord bot |
magikal-panel-api |
FastAPI backend for the web panel |
magikal-panel-web |
Static web frontend for the web panel |
Safe edit workflow¶
Before changing live code, make sure the working tree is clean.
Bot project:
cd /home/magikalbot/magikal-bot
git status
Good output:
On branch master
nothing to commit, working tree clean
Before a large or risky edit, create a restore point.
cd /home/magikalbot/magikal-bot
git add .
git commit -m "restore point before planned change"
Panel project:
cd /home/magikalbot/magikal-panel
git status
git add .
git commit -m "restore point before planned change"
Docs project:
cd /home/magikalbot/magikal-docs
git status
git add .
git commit -m "restore point before documentation change"
Bot service checks¶
Check bot status:
sudo systemctl status magikal-bot --no-pager
Restart bot:
sudo systemctl restart magikal-bot
Check recent bot logs:
sudo journalctl -u magikal-bot -n 100 --no-pager
Follow live bot logs:
sudo journalctl -u magikal-bot -f
Web panel service checks¶
Restart the panel API:
sudo systemctl restart magikal-panel-api
Restart the panel web frontend:
sudo systemctl restart magikal-panel-web
Check panel API logs:
sudo journalctl -u magikal-panel-api -n 100 --no-pager
Check panel web logs:
sudo journalctl -u magikal-panel-web -n 100 --no-pager
Documentation workflow¶
Edit docs as magikalbot:
cd /home/magikalbot/magikal-docs
Build the docs:
./.venv/bin/mkdocs build
Good output:
INFO - Documentation built in ...
Commit docs changes:
git status
git add .
git commit -m "update documentation"
Emergency rollback¶
Use Git to inspect recent commits:
git log --oneline --max-count=10
Rollback should be planned carefully. Do not reset or revert live code unless the target commit is understood.
For a safe investigation, first inspect what changed:
git show --stat
git show --name-only
Safety notes¶
- Keep persistent bot data in Postgres.
- Do not introduce SQLite unless explicitly approved.
- Avoid logging raw Discord IDs, mentions, secrets, or personal data.
- Use hashed PIDs for user-related records.
- Use UK date format in user-facing embeds and documentation examples.
- Before a wide or risky change, create a Git restore point first.