89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# Operations (Runbook)
|
|
|
|
## Deployment
|
|
|
|
### Development (bind mount + hot reload)
|
|
|
|
```bash
|
|
cd bot
|
|
docker compose -f docker-compose.dev.yml up -d --build
|
|
```
|
|
|
|
### Production (immutable image)
|
|
|
|
```bash
|
|
git pull
|
|
docker compose build telegram-bot
|
|
docker compose up -d telegram-bot
|
|
```
|
|
|
|
Production uses the `production` Dockerfile target: source compiled into `dist/`,
|
|
deps installed with `--omit=dev`, no host source bind-mount.
|
|
|
|
## Environment
|
|
|
|
All config via `.env` (see `.env.example`). Secrets in the repo's `../SECRETS.md`.
|
|
The container joins external network `mem0_net` to reach `mem0-postgres` and `litellm`.
|
|
|
|
### Memory (user long-term memory, D17)
|
|
|
|
- `SUMMARY_ENABLED` (default `true`) — `false`/`0` disables both `user_memory` reads/writes and summarization (falls back to `NoopMemory`).
|
|
- `SUMMARY_MODEL` (optional) — LiteLLM model alias for background summarization; empty = reuse `LLM_MODEL` (`mem0-openai`). Set a cheaper alias here if desired.
|
|
|
|
## Webhook go-live checklist
|
|
|
|
1. Confirm `bot.digikedai.com` DNS/CF-tunnel route reaches this container (`:8080`).
|
|
2. Set `TELEGRAM_WEBHOOK_URL` + `TELEGRAM_WEBHOOK_SECRET` in `.env`.
|
|
3. Restart; the bot calls `setWebhook` on boot.
|
|
4. Verify: `curl -s https://api.telegram.org/bot<TOKEN>/getWebhookInfo` shows the correct URL and no `last_error_message`.
|
|
|
|
### Deployment notes
|
|
|
|
- **Container**: `digikedai-bot` (build target `production`), restart `unless-stopped`.
|
|
- **Networks**: joins the external networks that host Postgres/LiteLLM (`mem0_net`) and the ingress (`bridge_hoelee`).
|
|
- **Ingress**: a Cloudflare tunnel routes the public hostname → **`http://digikedai-bot:8080`** directly (no reverse-proxy hop). The bot's Hono server serves `/health`, `/` (JSON), and `POST /<secret>/webhook`.
|
|
- **Webhook secret**: set via `TELEGRAM_WEBHOOK_SECRET` in `.env` (see `.env.example`).
|
|
- **LLM**: LiteLLM model alias `mem0-openai` (NOT `gpt-5-mini` — LiteLLM only serves declared aliases).
|
|
- **Redeploy after code change**: `git pull` then `docker compose -f docker-compose.yml up -d --build` (or `--force-recreate` for env-only changes).
|
|
|
|
## Health checks
|
|
|
|
- HTTP: `GET /health` → `{"status":"ok"}`.
|
|
- DB: the bot self-migrates on startup; a failed migration aborts boot (fail-fast).
|
|
- Telegram: `getWebhookInfo` (above) for delivery errors.
|
|
|
|
## Logs
|
|
|
|
```bash
|
|
docker logs -f digikedai-bot
|
|
```
|
|
|
|
JSON in production (pino), pretty in development. Internal errors carry full detail;
|
|
user-facing replies never expose stack traces or secrets (spec §14.1).
|
|
|
|
## Backups
|
|
|
|
- Postgres data is on the DSM `mem0` volume (`mem0-postgres`). Backups are the DSM
|
|
stack's responsibility (duplicati / DSM snapshot); the `bot` database lives inside
|
|
the same `mem0-postgres` data dir, so it is covered by existing backups.
|
|
- Conversation audit trail = `message` table.
|
|
|
|
## Common failures
|
|
|
|
| Symptom | Likely cause | Fix |
|
|
|---|---|---|
|
|
| Bot doesn't reply in prod | Webhook not set / route unreachable | `getWebhookInfo`; check tunnel/Traefik; ensure `setWebhook` ran |
|
|
| Dev bot uses polling unexpectedly | `TELEGRAM_WEBHOOK_URL` unset | Expected in dev; or set the URL for webhook |
|
|
| Startup aborts at migration | Postgres unreachable / bad password | Check `mem0_net` attachment and `POSTGRES_*` in `.env` |
|
|
| LLM errors | LiteLLM unreachable or model name wrong | Verify `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL` |
|
|
|
|
## Rollback
|
|
|
|
Redeploy a prior image tag (or rebuild from the previous commit):
|
|
|
|
```bash
|
|
git checkout <previous-commit>
|
|
docker compose build telegram-bot
|
|
docker compose up -d telegram-bot
|
|
```
|