# DigitalOcean — Telegram Bot Second Container Runbook

This runbook is for deploying the Gated Alpha Telegram bot as a separate app/container on DigitalOcean App Platform.

## Goal
Run bot worker independently from API using:

```bash
node dist/src/tg-bot/server.js
```

## Why separate container
- Independent restart/scaling from API
- Cleaner failure isolation (bot ingest vs API serving)
- Safer deploy cadence

## Prerequisites
- API already deployed and reachable (e.g. `https://www.gatedalpha.xyz`)
- Valid Telegram bot token
- Shared `INTERNAL_API_SECRET` between bot + API

## Required env vars (bot container)
- `NODE_ENV=production`
- `API_BASE_URL=https://www.gatedalpha.xyz`
- `INTERNAL_API_SECRET=<same as API>`
- `TELEGRAM_BOT_TOKEN=<botfather token>`
- `TG_SETUP_TOKEN_TTL_SECONDS=900`
- `TG_HEALTH_PORT=8081` (for health probes in long-polling mode)

Optional webhook mode:
- `TG_WEBHOOK_URL=https://<bot-app-domain>/tg-webhook`
- `TG_WEBHOOK_PORT=8443`
- `TG_WEBHOOK_SECRET=<random secret>`

## App Platform component (Worker) suggestion
- Type: **Worker** (preferred for long polling)
- Build command: `npm ci && npm run build`
- Run command: `node dist/src/tg-bot/server.js`

Ready-to-apply spec is now included at:
- `docs/do-bot-worker-app-spec.yaml`

Deploy helper script (preflight + apply) is included at:
- `docs/do-bot-worker-deploy.sh`

Example apply flow with `doctl`:
```bash
# create app from spec
cd alpha-claw
doctl apps create --spec docs/do-bot-worker-app-spec.yaml

# or update existing app
# doctl apps update <APP_ID> --spec docs/do-bot-worker-app-spec.yaml
```

Recommended (preflight enforced) flow:
```bash
cd alpha-claw
./docs/do-bot-worker-deploy.sh create
# or
./docs/do-bot-worker-deploy.sh update <APP_ID>
```

If using a Web Service instead:
- HTTP Port: `8081`
- Health check path: `/health`

## Health checks
In long-polling mode, bot now exposes:
- `GET /health` → liveness
- `GET /ready` → readiness

Response includes mode and uptime/known-group signals.

## Smoke test
After deploy:
1. Confirm logs show bot username and polling start.
2. Check health endpoint returns 200.
3. Run `/setup` from Telegram and verify wizard appears.
4. Post parseable tagged alpha in test group and verify ingest confirmation.

## Rollback
- Revert app to previous successful deployment in DO App Platform.
- Confirm `/health` recovers and bot can answer `/help`.