telegram-helper-bot/.cursor/rules/deployment-guide.md

Инструкция по деплою на продакшен

Общая информация

⚠️ ВАЖНО: Креды для доступа к серверу (SSH хост, порт, пользователь) предоставляются пользователем в запросе и НЕ должны сохраняться в этой документации!

Технологический стек:

• Python: 3.11.9
• Docker: Alpine Linux
• База данных: SQLite

Директория проекта на сервере: /home/prod/bots/telegram-helper-bot
Директория для команд инфраструктуры: /home/prod
База данных: /home/prod/bots/telegram-helper-bot/database/tg-bot-database.db

---

Этап 1: Подготовка на локальной машине

1.1. Проверка состояния репозитория

git status
git log --oneline -10
git diff master...HEAD --stat

1.2. Пуш ветки в репозиторий

git push -u origin <branch-name>

1.3. Создание Release Notes

ВАЖНО: Release notes создаются ПОСЛЕ пуша, чтобы не попали в репозиторий!

1. Использовать шаблон из .cursor/rules/release-notes-template.md
2. Создать файл RELEASE_NOTES_DEV-XX.md в корне проекта
3. Собрать информацию о коммитах:

   git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse
   

4. Заполнить release notes по шаблону:
   • Обзор (количество коммитов и основные направления)
   • Ключевые изменения (каждый значимый коммит)
   • Основные достижения (чекбоксы с эмодзи ✅)
   • Временная шкала разработки

Примечание: Release notes используются для Pull Request, затем файл удаляется из рабочей директории.

1.4. Создание дополнительной документации (если требуется)

ВАЖНО: Документацию создавать ПОСЛЕ пуша, чтобы она не попала в репозиторий!

1. Создать или обновить инструкции по деплою
2. Обновить необходимую техническую документацию
3. Убедиться, что не добавляются файлы с секретами

---

Этап 2: Деплой на сервер (тестовая ветка)

ВАЖНО: Креды для подключения к серверу должны быть предоставлены пользователем в запросе.

2.1. Подключение к серверу и остановка инфраструктуры

# Подключиться к серверу через SSH
# Перейти в директорию для команд инфраструктуры
cd /home/prod
make down

Проверка: Убедиться, что все контейнеры остановлены.

2.2. Создание бэкапа базы данных

cd /home/prod/bots/telegram-helper-bot/database
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db
ls -lh tg-bot-database*.db

ВАЖНО: Всегда создавать бэкап с timestamp перед применением миграций!

2.3. Переключение на ветку и подтягивание изменений

cd /home/prod/bots/telegram-helper-bot
git fetch origin
git checkout <branch-name>
git pull origin <branch-name>

2.4. Установка зависимостей (если изменились)

Если виртуальное окружение уже существует:

cd /home/prod/bots/telegram-helper-bot
.venv/bin/pip install -r requirements.txt

Если виртуального окружения нет:

cd /home/prod/bots/telegram-helper-bot
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

Примечание: Виртуальное окружение .venv на сервере используется только для применения миграций и утилит. Бот работает в Docker-контейнере.

2.5. Применение миграций базы данных

cd /home/prod/bots/telegram-helper-bot
.venv/bin/python scripts/apply_migrations.py

ВАЖНО:

• Миграции применяются ПЕРЕД запуском контейнеров
• База должна быть "спящей" (контейнеры выключены)
• Проверить вывод скрипта на наличие ошибок

Вывод при успехе:

📋 Найдено новых миграций: X
✅ Все миграции применены успешно (X шт.)

2.6. Запуск инфраструктуры

cd /home/prod
make up

2.7. Пересборка контейнера telegram-bot

Используем команду с гарантией применения изменений:

cd /home/prod
docker-compose up -d --build --force-recreate --no-deps telegram-bot

Что делает команда:

• --build - пересобирает образ
• --force-recreate - принудительно пересоздает контейнер
• --no-deps - не затрагивает зависимые сервисы
• Гарантирует доставку нового кода в контейнер без кэша

2.8. Проверка работоспособности

# Проверка статуса всех контейнеров
docker-compose ps

# Проверка логов telegram-bot
docker-compose logs telegram-bot --tail=50

# Или напрямую
docker logs bots_telegram_bot --tail=50

Что проверять в логах:

• ✅ База данных инициализирована
• ✅ Scoring Manager инициализирован (если используется)
• ✅ Metrics server запущен на порту 8080
• ✅ Нет критических ошибок
• ✅ Бот обрабатывает команды

На этом этапе: Ждать подтверждения от владельца о мердже ветки в master.

---

Этап 3: Финальный деплой на master

ВАЖНО: Выполняется только после подтверждения мерджа ветки в master!

3.1. Остановка инфраструктуры

cd /home/prod
make down

3.2. Переключение на master и получение изменений

cd /home/prod/bots/telegram-helper-bot
git checkout master
git pull origin master

Проверка: Убедиться, что получен коммит с мерджем.

3.3. Запуск инфраструктуры

cd /home/prod
make up

3.4. Пересборка контейнера telegram-bot с кодом master

cd /home/prod
docker-compose up -d --build --force-recreate --no-deps telegram-bot

3.5. Финальная проверка

# Статус контейнеров
docker-compose ps

# Логи
docker logs bots_telegram_bot --tail=50

Проверить:

• ✅ Все контейнеры в состоянии Up и healthy
• ✅ Логи не содержат критических ошибок
• ✅ Бот отвечает на команды в Telegram

3.6. Завершение работы

• Выйти с сервера
• Забыть все креды доступа (не сохранять их)

---

Troubleshooting

Проблема: Миграции не применяются

Решение:

1. Проверить, что контейнеры остановлены
2. Проверить права доступа к файлу БД
3. Посмотреть логи скрипта apply_migrations.py
4. Восстановить БД из бэкапа при необходимости:

   cd /home/prod/bots/telegram-helper-bot/database
   cp tg-bot-database_YYYYMMDD_HHMMSS.db tg-bot-database.db
   

Проблема: Контейнер не запускается

Решение:

1. Проверить логи контейнера:

   docker logs bots_telegram_bot --tail=100
   

2. Проверить переменные окружения в .env
3. Проверить healthcheck:

   docker inspect bots_telegram_bot | grep -A 20 Health
   

Проблема: Код не обновился в контейнере

Решение: Использовать принудительную пересборку без кэша:

docker-compose down telegram-bot
docker-compose build --no-cache telegram-bot
docker-compose up -d telegram-bot

Проблема: Нет виртуального окружения

Решение: Создать виртуальное окружение:

# Установить python3-venv (если нужно)
sudo apt install -y python3.11-venv

# Создать venv
cd /home/prod/bots/telegram-helper-bot
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

---

Последовательность действий для агента

Этап 1: Локальная подготовка

1. Проверить состояние репозитория (git status, git log)
2. Запушить ветку в репозиторий
3. Создать Release Notes по шаблону - ПОСЛЕ пуша!
4. Создать дополнительную документацию (если требуется) - ПОСЛЕ пуша!
5. Сообщить пользователю о готовности к деплою

Этап 2: Деплой на dev-ветку

1. Подключиться к серверу (креды из запроса пользователя)
2. Остановить инфраструктуру (make down из /home/prod)
3. Создать бэкап БД с timestamp
4. Переключиться на dev-ветку и подтянуть изменения
5. Установить/обновить зависимости Python (если требуется)
6. Применить миграции БД (через .venv/bin/python scripts/apply_migrations.py)
7. Проверить успешность применения миграций
8. Запустить инфраструктуру (make up)
9. Пересобрать контейнер telegram-bot с --build --force-recreate --no-deps
10. Проверить статус контейнеров и логи
11. Сообщить пользователю о готовности и ждать подтверждения "ОК"

Этап 3: Финальный деплой на master

Выполняется только после получения "ОК" от пользователя (означает мердж в master)

1. Остановить инфраструктуру
2. Переключиться на master и подтянуть изменения
3. Запустить инфраструктуру
4. Пересобрать контейнер telegram-bot с --build --force-recreate --no-deps
5. Проверить финальный статус и логи
6. Сообщить о успешном завершении деплоя
7. Завершить SSH-сессию и забыть все креды

---

Важные команды

Docker

# Просмотр всех контейнеров
docker-compose ps

# Логи конкретного сервиса
docker-compose logs <service-name> --tail=N

# Перезапуск конкретного сервиса
docker-compose restart <service-name>

# Остановка всей инфраструктуры
docker-compose down

# Запуск всей инфраструктуры
docker-compose up -d

# Пересборка без кэша
docker-compose build --no-cache <service-name>

# Принудительное пересоздание контейнера
docker-compose up -d --build --force-recreate --no-deps <service-name>

Git

# Проверка состояния
git status
git branch

# Переключение веток
git checkout <branch-name>

# Получение изменений
git fetch origin
git pull origin <branch-name>

# История коммитов
git log --oneline -N
git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse

Работа с БД

# Создание бэкапа с timestamp
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db

# Просмотр бэкапов
ls -lh tg-bot-database*.db

# Восстановление из бэкапа
cp tg-bot-database_BACKUP.db tg-bot-database.db

---

Примечания

1. Виртуальное окружение на сервере - используется только для запуска утилит и миграций. Бот работает в Docker-контейнере.

2. Бэкапы БД - создаются перед каждым применением миграций с timestamp в имени файла.

3. Пересборка контейнера - всегда использовать --force-recreate --no-deps для гарантии применения изменений.

4. Миграции - применяются только при остановленных контейнерах к "спящей" базе данных.

5. Release notes - создаются ПОСЛЕ пуша, чтобы не попадали в репозиторий. Используются для Pull Request, затем удаляются из рабочей директории.

6. Документация после пуша - вся документация и инструкции создаются ПОСЛЕ пуша в репозиторий, чтобы не попадали в коммиты и удалённый репозиторий.

7. Креды доступа - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды.

---

Контакты

При возникновении проблем или вопросов обращаться к владельцу проекта.