telegram-gateway/DEPLOY.md

Deploy telegram-gateway — Phase 1 (echo bot)

Procédure end-to-end pour mettre le gateway en ligne avec un bot arcodange_factory_bot (slug interne factory).

Phase 1 simplifiée : pas de Vault. Le Secret k8s telegram-gateway-bots est créé manuellement avec kubectl create secret. La migration vers Vault Secrets Operator se fait plus tard (Phase 2+) via vault.enabled: true dans chart/values.yaml.

---

1. Pré-requis

• Repo Gitea déjà créé : arcodange/telegram-gateway
• Bot Telegram déjà créé via @BotFather : @arcodange_factory_bot
  • Token : 8737289837:… (en variable d'env, jamais committé)
  • chat_id : récupéré via @userinfobot
• DNS : Cloudflare route déjà *.arcodange.fr vers le home lab → rien à faire côté DNS, le sous-domaine tg.arcodange.fr arrive au cluster dès qu'on déclare l'Ingress Traefik.

2. Push du repo (déclenche le build Docker)

cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
git init
git add .
git commit -m "Phase 1 MVP — echo bot factory"
git branch -M main
git remote add origin ssh://git@192.168.1.202:2222/arcodange/telegram-gateway.git
git push -u origin main

Gitea Actions build l'image et la pousse : gitea.arcodange.lab/arcodange/telegram-gateway:latest.

3. Créer le Secret k8s avec le token + secret_token

# Génère un secret_token frais (256 bits hex)
SECRET=$(openssl rand -hex 32)

# Le namespace est créé par ArgoCD si absent — on le crée explicitement avant
# pour pouvoir y poser le Secret tout de suite.
kubectl create namespace telegram-gateway --dry-run=client -o yaml | kubectl apply -f -

kubectl -n telegram-gateway create secret generic telegram-gateway-bots \
  --from-literal=BOT_FACTORY_TOKEN='8737289837:AAEVIygazfxgqJTxaxOh3X-mEoKaV7Rw1Gw' \
  --from-literal=BOT_FACTORY_SECRET="$SECRET"

# Garde $SECRET sous le coude pour l'étape 5 (setWebhook).
echo "secret_token = $SECRET"

Le bot est mappé sur le slug factory dans chart/values.yaml : BOT_FACTORY_TOKEN / BOT_FACTORY_SECRET correspondent. Pour ajouter d'autres bots ultérieurement, ajouter BOT_<UPPER_SLUG>_TOKEN/SECRET au même Secret + une clé sous bots: dans chart/values.yaml.

4. Activer l'Application ArgoCD

L'entrée telegram-gateway est ajoutée dans /Users/gabrielradureau/Work/Arcodange/factory/argocd/values.yaml (PR ouverte). Une fois la PR mergée :

kubectl -n argocd get app telegram-gateway -w
# attends Healthy + Synced
kubectl -n telegram-gateway logs deploy/telegram-gateway -f
# attends "telegram-gateway listening on :8080 (1 bot(s) loaded)"

# Smoke
curl -I https://tg.arcodange.fr/healthz   # → 200

5. Enregistrer le webhook côté Telegram

export BOT_FACTORY_TOKEN='8737289837:AAEVIygazfxgqJTxaxOh3X-mEoKaV7Rw1Gw'
export BOT_FACTORY_SECRET="$SECRET"     # même valeur qu'à l'étape 3
cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
make setwebhook SLUG=factory BASE_URL=https://tg.arcodange.fr
# → "webhook set: url=https://tg.arcodange.fr/bot/factory pending=0 last_err=\"\""

Vérification côté Telegram :

curl -s "https://api.telegram.org/bot$BOT_FACTORY_TOKEN/getWebhookInfo" | jq

6. Test réel

Envoyer n'importe quel message à @arcodange_factory_bot dans l'app Telegram → réponse identique en < 2 s. Pour le test /echo coucou répond coucou.

Troubleshooting

Symptôme	Action
Pod CreateContainerConfigError	Le Secret telegram-gateway-bots manque. Le créer (étape 3).
Pod CrashLoopBackOff "no bots in /etc/…/bots.yaml"	ConfigMap pas généré ou mal monté. kubectl get cm -n telegram-gateway -o yaml.
curl https://tg.arcodange.fr/healthz → 502/504	Ingress pas encore propagé OU le pod n'est pas Ready. kubectl describe ingress + kubectl describe pod.
setWebhook → Wrong response from the webhook: 401	BOT_FACTORY_SECRET côté Secret ≠ celui passé à setWebhook. Régénérer + recréer le Secret avec kubectl delete && create.
Webhook accepté mais pas de réponse Telegram	kubectl logs côté gateway → erreur sendMessage. Token bot invalide (révoqué via @BotFather ?) ou rate-limit Telegram.

Phase 2b — activer la queue Postgres async (optionnel)

Phase 2a (handler http sync) est livrée et active dès qu'un bot a handler: http.

Phase 2b (queue + worker) est désactivée tant que DATABASE_URL n'est pas dans le Secret. Pour activer :

1. Provisionner un user / une DB Postgres avec droits CREATE TABLE (le pod auto-applique la migration idempotente gateway_jobs au boot).

2. Ajouter le DSN au Secret existant :

   DSN='postgres://gateway:CHANGEME@pgbouncer.tools.svc.cluster.local:6432/gateway?sslmode=disable'
   kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
     {\"op\":\"add\",\"path\":\"/data/DATABASE_URL\",\"value\":\"$(echo -n "$DSN" | base64)\"}
   ]"
   kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
   

3. Vérifier dans les logs : queue + schema ready (db=postgres://gateway@…) puis worker started.

4. Configurer un bot avec async: true dans chart/values.yaml pour valider le pipeline.

Pour aller plus loin

• Phase 3 (pas livré) : handlers shell / script / ollama async, retry quand le Macbook Ollama est endormi.
• Phase 4 (pas livré) : passage à Vault (toggle vault.enabled: true + provisionner kvv2/telegram-gateway/config), Wake-on-LAN, multi-provider.

Plan complet : ~/.claude/plans/pour-les-notifications-on-inherited-seal.md.