kerrad/telegram-helper-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
telegram-helper-bot/.cursor/rules/deployment-guide.md

15 KiB
Raw Permalink Blame History

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

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

⚠️ ВАЖНО: Креды для доступа к серверу (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. Креды доступа - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды.

Контакты

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

Reference in New Issue View Git Blame Copy Permalink