mirror of
https://github.com/tiennm99/miti99bot.git
synced 2026-04-17 17:21:30 +00:00
tiennm99
4277f11c48
Add CLAUDE.md for AI assistant context. Create four new docs: deployment-guide.md (full deploy flow + secret rotation + rollback), code-standards.md (formatting, naming, module conventions, testing), codebase-summary.md (tech stack, modules, data flows, external APIs), development-roadmap.md (completed phases + planned work).
124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
# Deployment Guide
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js ≥ 20.6
|
|
- Cloudflare account with Workers + KV enabled
|
|
- Telegram bot token from [@BotFather](https://t.me/BotFather)
|
|
- `wrangler` CLI authenticated: `npx wrangler login`
|
|
|
|
## Environment Setup
|
|
|
|
### 1. Cloudflare KV Namespaces
|
|
|
|
```bash
|
|
npx wrangler kv namespace create miti99bot-kv
|
|
npx wrangler kv namespace create miti99bot-kv --preview
|
|
```
|
|
|
|
Paste returned IDs into `wrangler.toml`:
|
|
|
|
```toml
|
|
[[kv_namespaces]]
|
|
binding = "KV"
|
|
id = "<production-id>"
|
|
preview_id = "<preview-id>"
|
|
```
|
|
|
|
### 2. Worker Secrets
|
|
|
|
```bash
|
|
npx wrangler secret put TELEGRAM_BOT_TOKEN
|
|
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
|
|
```
|
|
|
|
`TELEGRAM_WEBHOOK_SECRET` — any high-entropy string (e.g. `openssl rand -hex 32`). grammY validates it on every webhook update via `X-Telegram-Bot-Api-Secret-Token`.
|
|
|
|
### 3. Local Dev Config
|
|
|
|
```bash
|
|
cp .dev.vars.example .dev.vars # for wrangler dev
|
|
cp .env.deploy.example .env.deploy # for register script
|
|
```
|
|
|
|
Both are gitignored. Fill in matching token + secret values.
|
|
|
|
`.env.deploy` also needs:
|
|
- `WORKER_URL` — the `*.workers.dev` URL (known after first deploy)
|
|
- `MODULES` — comma-separated, must match `wrangler.toml` `[vars].MODULES`
|
|
|
|
## Deploy
|
|
|
|
### First Time
|
|
|
|
```bash
|
|
npx wrangler deploy # learn the *.workers.dev URL
|
|
# paste URL into .env.deploy as WORKER_URL
|
|
npm run register:dry # preview payloads
|
|
npm run deploy # deploy + register webhook + commands
|
|
```
|
|
|
|
### Subsequent Deploys
|
|
|
|
```bash
|
|
npm run deploy
|
|
```
|
|
|
|
This runs `wrangler deploy` then `scripts/register.js` (setWebhook + setMyCommands).
|
|
|
|
### What the Register Script Does
|
|
|
|
`scripts/register.js` imports the same registry the Worker uses, builds it with a stub KV to derive public commands, then calls two Telegram APIs:
|
|
|
|
1. `setWebhook` — points Telegram at `WORKER_URL/webhook` with the secret token
|
|
2. `setMyCommands` — pushes public command list to Telegram's `/` menu
|
|
|
|
### Dry Run
|
|
|
|
```bash
|
|
npm run register:dry
|
|
```
|
|
|
|
Prints both payloads (webhook secret redacted) without calling Telegram.
|
|
|
|
## Secret Rotation
|
|
|
|
1. Generate new secret: `openssl rand -hex 32`
|
|
2. Update Cloudflare: `npx wrangler secret put TELEGRAM_WEBHOOK_SECRET`
|
|
3. Update `.env.deploy` with same value
|
|
4. Redeploy: `npm run deploy` (register step re-calls setWebhook with new secret)
|
|
|
|
Both values MUST match — mismatch causes 401 on every webhook.
|
|
|
|
## Adding/Removing Modules
|
|
|
|
When changing the active module list:
|
|
|
|
1. Update `MODULES` in `wrangler.toml` `[vars]`
|
|
2. Update `MODULES` in `.env.deploy`
|
|
3. If adding: ensure module exists in `src/modules/index.js` import map
|
|
4. `npm run deploy`
|
|
|
|
Removing a module from `MODULES` makes it inert — its KV data remains but nothing loads it.
|
|
|
|
## Rollback
|
|
|
|
Cloudflare Workers supports instant rollback via the dashboard or:
|
|
|
|
```bash
|
|
npx wrangler rollback
|
|
```
|
|
|
|
To disable a specific module without rollback, remove its name from `MODULES` and redeploy.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause | Fix |
|
|
|---------|-------|-----|
|
|
| 401 on all webhooks | Secret mismatch between CF secret and `.env.deploy` | Re-set both to same value, redeploy |
|
|
| Bot doesn't respond to commands | `MODULES` missing the module name | Add to both `wrangler.toml` and `.env.deploy` |
|
|
| `command conflict` at deploy | Two modules register same command name | Rename one command |
|
|
| `missing env: X` from register | `.env.deploy` incomplete | Add missing variable |
|
|
| `--env-file` not recognized | Node < 20.6 | Upgrade Node |
|
|
| `/help` missing a module | Module has no public or protected commands | Add at least one non-private command |
|