Talk.AI Safe Deployment Guide¶

Полное руководство по безопасному deployment с Blue-Green архитектурой и автоматическим управлением версиями.

КРИТИЧЕСКИ ВАЖНО: DEPLOYMENT ТОЛЬКО ПО РАЗРЕШЕНИЮ¶

🚫 АБСОЛЮТНЫЙ ЗАПРЕТ НА DEPLOYMENT БЕЗ РАЗРЕШЕНИЯ ПОЛЬЗОВАТЕЛЯ

❌ КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО: - Запуск deployment команд без явного разрешения - Автоматический deployment при исправлении проблем - Предположения что "пользователь хочет деплой" - Любые удаленные действия без команды пользователя

✅ ОБЯЗАТЕЛЬНО: - ОСТАНОВИТЬСЯ и НЕ выполнять удаленные действия - СООБЩИТЬ: "Код исправлен локально, deployment требует вашего разрешения" - ДОЖДАТЬСЯ явной команды пользователя на deployment

Единственная команда deployment¶

Основная команда (ЕДИНСТВЕННАЯ РЕКОМЕНДУЕМАЯ)¶

make deploy

Все остальные команды:

make deploy-prod    # Алиас для make deploy  
make deploy-vps     # Алиас для make deploy

Blue-Green Deployment Архитектура¶

ЗОЛОТОЕ ПРАВИЛО: make deploy автоматически выполняет весь безопасный процесс!

Автоматическая последовательность (deploy-orchestrator.sh)¶

1. Подготовка артефактов (deploy-prepare.sh):

✅ Сборка Go backend (production оптимизация)
✅ Сборка React frontend для production домена
✅ Создание Docker образов с правильными тегами
✅ Архивирование для передачи на VPS

2. Blue-Green Deployment (deploy-blue-green.sh --yes):

✅ Определение текущего окружения (blue/green)
✅ Развертывание в неактивном окружении
✅ 5 Smoke tests (API, Database, Frontend, Health, Scenarios)
✅ Переключение nginx трафика БЕЗ downtime
✅ Очистка старого окружения через 5 секунд

КРИТИЧНО: Автоматические Smoke Tests¶

Обязательные проверки перед переключением трафика:

GET /api/health → 200 OK
GET /api/scenarios → возвращает сценарии
GET / → frontend загружается
Database connectivity → Supabase доступен
Container status → healthy state

При провале ЛЮБОЙ проверки → автоматический rollback!

Правильное управление секретами¶

Обязательные секреты в .env файле¶

Локально (для разработки):

# .env в корне проекта (НЕ в git)
OPENAI_API_KEY=sk-proj-your-openai-api-key-here
SUPABASE_ANON_KEY=your-supabase-anon-key-here  
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key-here

VPS Production (.env на сервере):

# /opt/talk-ai/.env (НЕ в контейнере!)
OPENAI_API_KEY=sk-proj-your-production-key
SUPABASE_ANON_KEY=your-production-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-production-service-role-key

Cloud-Native архитектура¶

✅ ПРАВИЛЬНАЯ архитектура:

Единый контейнер: backend + frontend
Supabase managed database: облачная PostgreSQL
REST API подключения: через HTTPS к Supabase
Никаких локальных БД в контейнере

❌ ЗАПРЕЩЕННАЯ архитектура:

Локальная БД в контейнере
Несколько контейнеров для одного проекта
Прямые SQL подключения к БД

Автоматическое управление версиями¶

ЗОЛОТОЕ ПРАВИЛО: ALL commit команды ДОЛЖНЫ использовать make!

# ЗАПРЕЩЕНО - прямые git команды
git commit -m "some message"

# ОБЯЗАТЕЛЬНО - только make команды  
make commit MSG="fix: исправить evaluation API"        # patch: 1.1.0 → 1.1.1
make commit-minor MSG="feat: новая функция"           # minor: 1.1.0 → 1.2.0  
make commit-major MSG="BREAKING: новая архитектура"   # major: 1.1.0 → 2.0.0

Обязательный процесс перед deployment¶

КРИТИЧЕСКИЕ проверки (ОБЯЗАТЕЛЬНО)¶

ПЕРЕД запуском make deploy агент ДОЛЖЕН проверить:

# 1. Все 4 API ключа переданы в контейнер
docker exec talk-ai-app printenv | grep -E "(OPENAI|SUPABASE)" | wc -l
# Должно быть: 4 ключа

# 2. AI API работает  
curl -s http://localhost:8090/api/ai-models > /dev/null && echo "AI API работает"

# 3. Supabase подключение работает
curl -s http://localhost:8090/api/scenarios > /dev/null && echo "Supabase работает"

# 4. Smoke тесты проходят на 100%
make test-smoke
# Exit code ДОЛЖЕН быть 0

Автоматический deployment процесс¶

После команды make deploy происходит:

Phase 1: Подготовка (deploy-prepare.sh)

✅ Локальная сборка Go backend с production флагами
✅ Локальная сборка React frontend для production домена  
✅ Создание Docker образов с версионными тегами
✅ Упаковка артефактов для передачи на VPS

Phase 2: Blue-Green Switch (deploy-blue-green.sh)

✅ SSH подключение к VPS
✅ Определение текущего окружения (blue vs green)
✅ Развертывание в неактивном окружении
✅ 5 Smoke tests на новом окружении
✅ Переключение nginx трафика (0 downtime)
✅ Cleanup старого окружения

Phase 3: Автоматическая валидация

✅ Health check API endpoints
✅ Frontend доступность проверка
✅ Database connectivity валидация
✅ Performance metrics сбор

Системы безопасности¶

Обязательные проверки готовности¶

Система готова к deployment ТОЛЬКО если:

✅ Все 4 ключа есть в контейнере: docker exec talk-ai-app printenv | grep -E "(OPENAI|SUPABASE)" | wc -l = 4
✅ AI API отвечает: GET /api/ai-models возвращает модели
✅ Supabase работает: GET /api/scenarios возвращает сценарии
✅ Smoke тесты проходят: make test-smoke exit code = 0

Автоматический Rollback¶

Blue-Green система автоматически откатывается при:

❌ Провале ANY из 5 smoke tests
❌ API endpoints не отвечают за 30 секунд
❌ Frontend не загружается
❌ Database connectivity lost
❌ Container fails to start

Защита секретов¶

✅ ПРАВИЛЬНО:

API ключи в .env файле (НЕ в git)
config.yaml использует ${OPENAI_API_KEY} переменные
Makefile загружает .env: set -a; [ -f .env ] && . ./.env; set +a
Проверка передачи в контейнер перед deployment

❌ КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО:

Прямые ключи в config.yaml: api_key: "sk-proj-real-key"
Ключи в Makefile без загрузки .env
Deployment без проверки что ключи переданы
Коммиты с реальными API ключами в коде

Диагностика проблем¶

Проверка логов и статуса¶

# Локальный контейнер логи
make logs-rotate

# VPS production логи  
ssh cloud-user@talk-ai.saga.surf "docker logs talk-ai-app"

# VPS статус Blue-Green окружений
ssh cloud-user@talk-ai.saga.surf "cd /opt/talk-ai && ls -la blue/ green/"

Типичные проблемы и решения¶

1. API ключи не переданы в контейнер:

# Диагностика
docker exec talk-ai-app printenv | grep -E "(OPENAI|SUPABASE)" | wc -l
# Если НЕ равно 4, то проблема с .env

# Решение: проверить .env и пересобрать контейнер
make restart

2. Smoke тесты падают:

# Диагностика
make test-smoke
echo "Exit code: $?"  # Должен быть 0

# Если падают - проверить конкретные API
curl http://localhost:8090/api/health
curl http://localhost:8090/api/scenarios

3. Deployment завис:

# Blue-Green deployment должен завершиться за 2-3 минуты
# Если завис - проверить VPS доступность
ssh cloud-user@talk-ai.saga.surf "docker ps"

# При необходимости - manual rollback
ssh cloud-user@talk-ai.saga.surf "cd /opt/talk-ai && ./deploy-rollback.sh"

Целевые метрики качества¶

Production готовность¶

100% smoke tests перед КАЖДЫМ deployment
0 downtime благодаря Blue-Green architecture
< 2 минуты полное время deployment включая rollback capability
Автоматический rollback при ANY провале health checks

Безопасность и надежность¶

0 hardcoded секретов в production коде
4/4 API ключа всегда присутствуют в контейнере
Supabase managed database - нет риска потери локальных данных
Автоматические git теги для каждого deployment

Операционная эффективность¶

Единая команда make deploy для любого агента
Запрет manual deployment без разрешения пользователя
Автоматическая валидация перед каждым действием
Zero-surprise deployments - все предсказуемо

АБСОЛЮТНЫЕ правила для агентов¶

🚫 КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО:¶

Deployment без разрешения: НИКОГДА не запускать make deploy без явной команды пользователя
Ручные git коммиты: ТОЛЬКО make commit, make commit-minor, make commit-major
Пропуск smoke tests: ВСЕГДА make test-smoke перед deployment
Игнорирование API ключей: ОБЯЗАТЕЛЬНО проверить docker exec talk-ai-app printenv | grep -E "(OPENAI|SUPABASE)"

ОБЯЗАТЕЛЬНЫЙ workflow:¶

# 1. Исправляю код локально
# (тут изменения в файлах)

# 2. ОБЯЗАТЕЛЬНО пересобираю контейнер
make restart

# 3. ОБЯЗАТЕЛЬНО проверяю готовность
make test-smoke  # Должен быть exit code 0
curl http://localhost:8090/api/health  # Должен отвечать
curl http://localhost:8090/api/scenarios  # Должен возвращать данные

# 4. ОСТАНАВЛИВАЮСЬ и сообщаю пользователю
# "Код исправлен локально и протестирован. Deployment требует вашего разрешения."

# 5. ДОЖИДАЮСЬ команды пользователя
# ТОЛЬКО после "разрешаю deployment" запускаю:
make deploy

🎁 Преимущества для команды¶

Для разработчиков:¶

Нет страха deployment - автоматический rollback защищает
Единые команды во всех проектах
Предсказуемый результат каждого deployment

Для DevOps:¶

Zero manual intervention в нормальных случаях
Полная трассировка всех изменений через git теги
Cloud-native архитектура БЕЗ администрирования БД

👥 Для менеджмента:¶

Нулевой risk незапланированных deployment
Прозрачность всех изменений системы
Быстрое время восстановления при проблемах

🏆 ЗАКЛЮЧЕНИЕ: Production-Ready Система¶

Talk.AI deployment система соответствует стандартам Enterprise уровня:

✅ Zero-downtime deployments с Blue-Green архитектурой
✅ Автоматические safety nets и rollback capability
✅ Comprehensive validation перед каждым действием
✅ Cloud-native security с managed database
✅ Full audit trail через автоматические git теги

Принцип: "Безопасность прежде скорости, автоматизация прежде manual действий"