411 lines
15 KiB
Markdown
411 lines
15 KiB
Markdown
# Инструкция по деплою на продакшен
|
||
|
||
## Общая информация
|
||
|
||
**⚠️ ВАЖНО:** Креды для доступа к серверу (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. Проверка состояния репозитория
|
||
|
||
```bash
|
||
git status
|
||
git log --oneline -10
|
||
git diff master...HEAD --stat
|
||
```
|
||
|
||
### 1.2. Пуш ветки в репозиторий
|
||
|
||
```bash
|
||
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. Собрать информацию о коммитах:
|
||
```bash
|
||
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. Подключение к серверу и остановка инфраструктуры
|
||
|
||
```bash
|
||
# Подключиться к серверу через SSH
|
||
# Перейти в директорию для команд инфраструктуры
|
||
cd /home/prod
|
||
make down
|
||
```
|
||
|
||
**Проверка:** Убедиться, что все контейнеры остановлены.
|
||
|
||
### 2.2. Создание бэкапа базы данных
|
||
|
||
```bash
|
||
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. Переключение на ветку и подтягивание изменений
|
||
|
||
```bash
|
||
cd /home/prod/bots/telegram-helper-bot
|
||
git fetch origin
|
||
git checkout <branch-name>
|
||
git pull origin <branch-name>
|
||
```
|
||
|
||
### 2.4. Установка зависимостей (если изменились)
|
||
|
||
#### Если виртуальное окружение уже существует:
|
||
|
||
```bash
|
||
cd /home/prod/bots/telegram-helper-bot
|
||
.venv/bin/pip install -r requirements.txt
|
||
```
|
||
|
||
#### Если виртуального окружения нет:
|
||
|
||
```bash
|
||
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. Применение миграций базы данных
|
||
|
||
```bash
|
||
cd /home/prod/bots/telegram-helper-bot
|
||
.venv/bin/python scripts/apply_migrations.py
|
||
```
|
||
|
||
**ВАЖНО:**
|
||
- Миграции применяются **ПЕРЕД** запуском контейнеров
|
||
- База должна быть "спящей" (контейнеры выключены)
|
||
- Проверить вывод скрипта на наличие ошибок
|
||
|
||
**Вывод при успехе:**
|
||
```
|
||
📋 Найдено новых миграций: X
|
||
✅ Все миграции применены успешно (X шт.)
|
||
```
|
||
|
||
### 2.6. Запуск инфраструктуры
|
||
|
||
```bash
|
||
cd /home/prod
|
||
make up
|
||
```
|
||
|
||
### 2.7. Пересборка контейнера telegram-bot
|
||
|
||
Используем команду с гарантией применения изменений:
|
||
|
||
```bash
|
||
cd /home/prod
|
||
docker-compose up -d --build --force-recreate --no-deps telegram-bot
|
||
```
|
||
|
||
**Что делает команда:**
|
||
- `--build` - пересобирает образ
|
||
- `--force-recreate` - принудительно пересоздает контейнер
|
||
- `--no-deps` - не затрагивает зависимые сервисы
|
||
- Гарантирует доставку нового кода в контейнер без кэша
|
||
|
||
### 2.8. Проверка работоспособности
|
||
|
||
```bash
|
||
# Проверка статуса всех контейнеров
|
||
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. Остановка инфраструктуры
|
||
|
||
```bash
|
||
cd /home/prod
|
||
make down
|
||
```
|
||
|
||
### 3.2. Переключение на master и получение изменений
|
||
|
||
```bash
|
||
cd /home/prod/bots/telegram-helper-bot
|
||
git checkout master
|
||
git pull origin master
|
||
```
|
||
|
||
**Проверка:** Убедиться, что получен коммит с мерджем.
|
||
|
||
### 3.3. Запуск инфраструктуры
|
||
|
||
```bash
|
||
cd /home/prod
|
||
make up
|
||
```
|
||
|
||
### 3.4. Пересборка контейнера telegram-bot с кодом master
|
||
|
||
```bash
|
||
cd /home/prod
|
||
docker-compose up -d --build --force-recreate --no-deps telegram-bot
|
||
```
|
||
|
||
### 3.5. Финальная проверка
|
||
|
||
```bash
|
||
# Статус контейнеров
|
||
docker-compose ps
|
||
|
||
# Логи
|
||
docker logs bots_telegram_bot --tail=50
|
||
```
|
||
|
||
**Проверить:**
|
||
- ✅ Все контейнеры в состоянии `Up` и `healthy`
|
||
- ✅ Логи не содержат критических ошибок
|
||
- ✅ Бот отвечает на команды в Telegram
|
||
|
||
### 3.6. Завершение работы
|
||
|
||
- Выйти с сервера
|
||
- Забыть все креды доступа (не сохранять их)
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Проблема: Миграции не применяются
|
||
|
||
**Решение:**
|
||
1. Проверить, что контейнеры остановлены
|
||
2. Проверить права доступа к файлу БД
|
||
3. Посмотреть логи скрипта apply_migrations.py
|
||
4. Восстановить БД из бэкапа при необходимости:
|
||
```bash
|
||
cd /home/prod/bots/telegram-helper-bot/database
|
||
cp tg-bot-database_YYYYMMDD_HHMMSS.db tg-bot-database.db
|
||
```
|
||
|
||
### Проблема: Контейнер не запускается
|
||
|
||
**Решение:**
|
||
1. Проверить логи контейнера:
|
||
```bash
|
||
docker logs bots_telegram_bot --tail=100
|
||
```
|
||
2. Проверить переменные окружения в `.env`
|
||
3. Проверить healthcheck:
|
||
```bash
|
||
docker inspect bots_telegram_bot | grep -A 20 Health
|
||
```
|
||
|
||
### Проблема: Код не обновился в контейнере
|
||
|
||
**Решение:**
|
||
Использовать принудительную пересборку без кэша:
|
||
```bash
|
||
docker-compose down telegram-bot
|
||
docker-compose build --no-cache telegram-bot
|
||
docker-compose up -d telegram-bot
|
||
```
|
||
|
||
### Проблема: Нет виртуального окружения
|
||
|
||
**Решение:**
|
||
Создать виртуальное окружение:
|
||
```bash
|
||
# Установить 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
|
||
|
||
```bash
|
||
# Просмотр всех контейнеров
|
||
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
|
||
|
||
```bash
|
||
# Проверка состояния
|
||
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
|
||
```
|
||
|
||
### Работа с БД
|
||
|
||
```bash
|
||
# Создание бэкапа с 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. **Креды доступа** - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды.
|
||
|
||
---
|
||
|
||
## Контакты
|
||
|
||
При возникновении проблем или вопросов обращаться к владельцу проекта.
|