telegram-gateway/DEPLOY.md

Deploy homelab-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 homelab-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/homelab-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/homelab_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/homelab-gateway.git
git push -u origin main

Gitea Actions build l'image et la pousse : gitea.arcodange.lab/arcodange/homelab-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 homelab-gateway --dry-run=client -o yaml | kubectl apply -f -

kubectl -n homelab-gateway create secret generic homelab-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 homelab-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 homelab-gateway -w
# attends Healthy + Synced
kubectl -n homelab-gateway logs deploy/homelab-gateway -f
# attends "homelab-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/homelab_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 homelab-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 homelab-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.

Pour aller plus loin

• Phase 2 : handler http (forward vers svc interne) + queue Postgres durable.
• Phase 3 : handlers shell / script / ollama async, retry quand le Macbook Ollama est endormi.
• Phase 4 : passage à Vault (toggle vault.enabled: true + provisionner kvv2/homelab-gateway/config), Wake-on-LAN, multi-provider.

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