microdao-daarion/telegram-infrastructure/README.md

Telegram Infrastructure

Мінімальний стек для інтеграції Telegram-ботів з системою агентів DAGI/microDAO.

🏗️ Архітектура

Цей стек складається з трьох сервісів:

1. telegram-bot-api (Local Telegram Bot API)

• Офіційний Local Telegram Bot API від Telegram
• Працює в режимі --local (HTTP only, без SSL)
• Доступний тільки на 127.0.0.1:8081 (не публічний)
• Дозволяє використовувати Bot API без зовнішніх запитів до Telegram серверів

2. nats (Message Bus)

• NATS як шина подій між сервісами
• Простий режим без кластера
• Доступний на 127.0.0.1:4222

3. telegram-gateway (Python FastAPI)

• Міст між Telegram Bot API і NATS
• Базовий FastAPI сервіс з /healthz endpoint
• Буде розширений через Cursor для:
  • Читання апдейтів з Telegram
  • Публікації подій у NATS
  • Прийому HTTP команд від інших сервісів

📋 Передумови

• Docker + Docker Compose
• Telegram API credentials (API ID, API Hash) з https://my.telegram.org/apps
• Домен, що вказує на ваш сервер (опціонально для майбутнього HTTPS)

🚀 Швидкий старт

1. Налаштування змінних середовища

Створіть .env файл у кореневій директорії:

cp .env.example .env

Заповніть .env вашими значеннями:

TELEGRAM_API_ID=YOUR_API_ID
TELEGRAM_API_HASH=YOUR_API_HASH
GATEWAY_DOMAIN=gateway.daarion.city

2. Запуск стеку

docker compose up -d

3. Перевірка статусу

Перевірте, що всі контейнери запущені:

docker compose ps

Очікуваний вивід:

NAME                 STATUS    PORTS
telegram-bot-api     running   127.0.0.1:8081->8081/tcp
nats                 running   127.0.0.1:4222->4222/tcp
telegram-gateway     running   127.0.0.1:8000->8000/tcp

🧪 Тестування

1. Перевірка telegram-gateway

curl http://127.0.0.1:8000/healthz

Очікувана відповідь:

{
  "status": "ok",
  "service": "telegram-gateway",
  "telegram_api": "http://telegram-bot-api:8081",
  "nats": "nats://nats:4222"
}

2. Перевірка Local Telegram Bot API

Замініть <YOUR_BOT_TOKEN> на ваш реальний токен бота:

curl http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe

Очікувана відповідь (JSON з інформацією про бота):

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "YourBot",
    "username": "your_bot"
  }
}

3. Перевірка NATS

docker logs nats

Має показувати успішний запуск NATS сервера.

📁 Структура проєкту

telegram-infrastructure/
├── docker-compose.yml          # Конфігурація Docker Compose
├── .env                        # Змінні середовища (не в git)
├── .env.example               # Приклад змінних
├── README.md                   # Ця документація
├── data/                       # Дані (автоматично створюється)
│   └── telegram-bot-api/      # Дані Local Telegram Bot API
└── telegram-gateway/           # Telegram Gateway сервіс
    ├── Dockerfile
    ├── requirements.txt
    └── app/
        ├── __init__.py
        └── main.py            # FastAPI додаток

🔒 Безпека

• telegram-bot-api доступний тільки на localhost (127.0.0.1:8081)
• nats доступний тільки на localhost (127.0.0.1:4222)
• telegram-gateway доступний тільки на localhost (127.0.0.1:8000)
• Для публічного доступу додайте reverse proxy (Caddy/Traefik/nginx) з HTTPS

🔄 Управління

Зупинка сервісів

docker compose down

Перезапуск сервісу

docker compose restart telegram-gateway

Перегляд логів

# Всі сервіси
docker compose logs -f

# Конкретний сервіс
docker compose logs -f telegram-gateway

Rebuild після змін коду

docker compose up -d --build telegram-gateway

📝 Наступні кроки

Після того, як інфраструктура запрацює, використовуйте Cursor для розробки логіки telegram-gateway:

1. Інтеграція aiogram — для роботи з Telegram Bot API
2. NATS publisher — публікація подій у NATS
3. Webhook endpoints — прийом команд від інших сервісів
4. Message routing — маршрутизація повідомлень між агентами

🐛 Troubleshooting

Контейнери не запускаються

docker compose logs telegram-bot-api

Порти зайняті

Переконайтесь, що порти 8081, 4222, 8000 вільні:

lsof -i :8081
lsof -i :4222
lsof -i :8000

Проблеми з правами доступу

chmod -R 755 data/

📚 Посилання

• Local Telegram Bot API
• NATS
• FastAPI
• aiogram (для майбутньої інтеграції)