Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/deploy.sh
• README.md
• AGENTS.md
• package.json
• wrangler.jsonc (referenced in documentation)

The deployment process transitions the Telegram History Bot from a local development environment to the Cloudflare Workers production platform. This guide covers resource provisioning, environment configuration, and the two-stage safety deployment strategy.

Prerequisites and Local Setup

Before deploying, you must install dependencies and prepare Cloudflare resources.

1. Run npm install to load required development dependencies and production modules.
2. Execute the ./setup.sh script to automate the creation of KV namespaces and the D1 database.
3. Copy the generated resource IDs from the setup script output into your wrangler.jsonc file.
4. Apply the initial D1 database migrations using the command: npx wrangler d1 migrations apply summaries.

Sources: README.md:143-152, package.json:7-10

Environment Variables and Secrets

The bot requires specific secrets and configuration flags stored in Cloudflare's secure environment. You set these using the wrangler secret put command.

Required Secrets

Secret	Description
TOKEN	The Telegram Bot API token.
SECRET	A custom HMAC header string for webhook security validation.
OPENAI_API_KEY	API key for OpenAI provider access.
OPENAI_PREMIUM_API_KEY	API key for high-volume or premium model processing.

Sources: AGENTS.md:52-54, README.md:154-159

Summary Optimization Configuration

The bot includes an optimized summary system that you can toggle and tune via environment variables.

Variable	Default	Description
SUMMARY_OPT_ENABLED	true	Main toggle for the optimized summary system.
SUMMARY_OPT_MAX_WORKERS	5	Maximum number of parallel workers.
SUMMARY_OPT_MAX_TOKENS_PER_REQUEST	120000	Token budget for AI requests.
SUMMARY_OPT_HIERARCHICAL_ENABLED	true	Enables two-stage processing for large datasets.

Sources: README.md:109-122

Safe Deployment Strategy

The project utilizes a two-stage deployment process via scripts/deploy.sh to ensure system stability when enabling new features like the optimized summary system.

Stage 1: Validation and Baseline Deploy

The script first validates the codebase by running npm test and checking TypeScript types with npx tsc --noEmit. If these checks pass, it disables the optimized summary feature (SUMMARY_OPT_ENABLED=false) and deploys the worker to Cloudflare.

Stage 2: Feature Activation

After a 30-second stabilization period, the script prompts for user confirmation to enable the optimized system. Upon confirmation, it sets SUMMARY_OPT_ENABLED=true via Cloudflare secrets.

Sources: scripts/deploy.sh:30-73

Deployment Flow Diagram

The following diagram illustrates the automated deployment logic found in the deployment script.

Post-Deployment Monitoring

Once deployed, you should monitor the bot's health and performance using the Cloudflare Wrangler CLI.

• Live Logs: Run npx wrangler tail --format=pretty to view real-time execution logs.
• Feature Tracking: Filter logs using grep "Optimized summary" to track the performance of the optimization engine.
• Emergency Rollback: If the system becomes unstable, disable optimization immediately by running:
  npx wrangler secret put SUMMARY_OPT_ENABLED --text "false"

Sources: scripts/deploy.sh:88-99, README.md:126-135

The bot is designed for high reliability with automatic fallbacks. If the optimized summary system fails, the worker automatically reverts to the legacy summarization logic to ensure service continuity.

Sources: README.md:131-133, AGENTS.md:103-106