Руководство по деплою (CI/CD)

В Gifty используется современный пайплайн автоматического деплоя, обеспечивающий Zero-Downtime (отсутствие простоев) и гарантирующий качество кода через обязательное тестирование.

Архитектура деплоя

Мы используем стратегию Blue-Green Deployment (Сине-зеленое развертывание) с использованием Nginx на хостовой машине и Docker Compose для контейнеризации.

Как это работает:

Два слота: На сервере зарезервировано два порта: 8000 и 8001.
Health Checks: Новая версия приложения запускается в свободном "слоте". Docker и наш скрипт деплоя проверяют эндпоинт /health.
Бесшовное переключение: Nginx переключает трафик на новый порт только после того, как приложение подтвердило свою готовность.
Безопасный откат: Если новая версия не запустилась, старая продолжает работать без прерывания обслуживания.

Пайплайн GitHub Actions

Процесс деплоя описан в файле .github/workflows/deploy-prod.yml. Он состоит из двух основных этапов:

1. Этап Тестирования (`test`)

Запускается на каждом пуше в main.

Поднимает окружение (Python 3.11).
Устанавливает зависимости.
Запускает pytest с учетом настроек в tests_config.yaml.
Если тесты упали, деплой не начнется.

2. Этап Деплоя (`deploy`)

Запускается по SSH на целевом сервере:

SCP: Копирует актуальный код в папку /app/gifty-backend.
Build: Собирает новый Docker-образ.
Switch: Выполняет скрипт scripts/deploy.sh для переключения портов и обновления конфига Nginx.

Настройка сервера

Для работы деплоя на сервере должны быть выполнены следующие условия:

1. Конфигурация Nginx

Nginx должен использовать динамический файл upstream. В конфиге сайта (/etc/nginx/sites-enabled/gifty):

include /etc/nginx/conf.d/gifty_upstream.conf;

server {
    ...
    location / {
        proxy_pass http://gifty_backend;
    }
}

2. Права доступа

Пользователь, под которым GitHub подключается по SSH, должен иметь права на:

Выполнение docker-compose.
Перезапись файла в /etc/nginx/conf.d/.
Выполнение sudo nginx -s reload без пароля (или через соответствующие sudoers).

Настройка GitHub Secrets

В настройках репозитория (Settings -> Secrets) должны быть заданы:

Секрет	Описание
`PROD_SSH_HOST`	IP или домен сервера
`PROD_SSH_PORT`	Порт SSH (если не 22)
`PROD_SSH_USER`	Имя пользователя для подключения
`PROD_SSH_KEY`	Приватный SSH ключ
`PROD_ENV_FILE`	Содержимое файла `.env` для продакшена

Мониторинг деплоя

Статус текущего деплоя можно отследить во вкладке Actions в GitHub.

Деплой документации

Процесс деплоя документации описан в .github/workflows/docs.yml и привязан к ветке documentation.

Правила работы:

Основная ветка: documentation. Только пуш в эту ветку вызывает обновление сайта dev.giftyai.ru.
Рабочие ветки: documentation/*. При пуше в эти ветки запускается только проверка сборки (mkdocs build), чтобы вы могли убедиться в отсутствии ошибок.
Pull Request: При создании PR в ветку documentation также запускается проверка. Деплой произойдет только после слияния PR.