mirror of https://github.com/tiennm99/miti99bot.git synced 2026-04-17 15:20:58 +00:00

Files

tiennm99 4277f11c48 docs: add CLAUDE.md and project documentation

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).

2026-04-14 15:28:53 +07:00

3.5 KiB

Raw Blame History

Deployment Guide

Prerequisites

Node.js ≥ 20.6
Cloudflare account with Workers + KV enabled
Telegram bot token from @BotFather
wrangler CLI authenticated: npx wrangler login

Environment Setup

1. Cloudflare KV Namespaces

npx wrangler kv namespace create miti99bot-kv
npx wrangler kv namespace create miti99bot-kv --preview

Paste returned IDs into wrangler.toml:

[[kv_namespaces]]
binding = "KV"
id = "<production-id>"
preview_id = "<preview-id>"

2. Worker Secrets

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

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

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

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:

setWebhook — points Telegram at WORKER_URL/webhook with the secret token
setMyCommands — pushes public command list to Telegram's / menu

Dry Run

npm run register:dry

Prints both payloads (webhook secret redacted) without calling Telegram.

Secret Rotation

Generate new secret: openssl rand -hex 32
Update Cloudflare: npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
Update .env.deploy with same value
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:

Update MODULES in wrangler.toml [vars]
Update MODULES in .env.deploy
If adding: ensure module exists in src/modules/index.js import map
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:

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

3.5 KiB Raw Blame History