quiz_test/docs/DOCKER_README.md

Docker & CI/CD Deployment Guide

Этот документ описывает настройку и использование Docker контейнеризации и CI/CD pipeline для Quiz Bot.

🐳 Docker Setup

Требования

• Docker 20.10+
• Docker Compose 2.0+
• 1GB свободного места на диске
• 512MB RAM для контейнера

Быстрый старт для разработки

1. Клонируйте репозиторий:

git clone <repository-url>
cd quiz-bot

2. Настройте переменные окружения:

cp .env.example .env
# Отредактируйте .env файл, добавьте ваш BOT_TOKEN

3. Запустите с помощью скрипта:

./scripts/dev.sh run

Ручной запуск через Docker Compose

# Сборка и запуск
docker-compose up --build -d

# Просмотр логов
docker-compose logs -f

# Остановка
docker-compose down

🔧 Доступные скрипты

Development Script (scripts/dev.sh)

./scripts/dev.sh build      # Собрать образ
./scripts/dev.sh run        # Запустить в dev режиме
./scripts/dev.sh test       # Запустить тесты
./scripts/dev.sh logs       # Показать логи
./scripts/dev.sh cleanup    # Очистить ресурсы

Production Script (scripts/deploy.sh)

./scripts/deploy.sh deploy    # Деплой в production
./scripts/deploy.sh monitor   # Мониторинг сервисов
./scripts/deploy.sh rollback  # Откат версии
./scripts/deploy.sh logs      # Production логи

🚀 CI/CD Pipeline (Drone)

Структура Pipeline

Pipeline состоит из следующих этапов:

1. Prepare - Подготовка и информация о коммите
2. Lint - Проверка кода (Black, isort, flake8, mypy)
3. Test - Запуск unit тестов
4. Security - Проверка безопасности (Safety, Bandit)
5. Build - Сборка Docker образа
6. Test Docker - Тестирование контейнера
7. Deploy Staging - Деплой в staging (ветка develop)
8. Deploy Production - Деплой в production (ветка main)
9. Notify - Уведомления о результате

Настройка Drone

1. Создайте секреты в Drone:

# Токены для разных сред
drone secret add repo/quiz-bot bot_token_staging "your_staging_bot_token"
drone secret add repo/quiz-bot bot_token_production "your_production_bot_token"

# Webhook для уведомлений
drone secret add repo/quiz-bot notification_webhook "your_webhook_url"

2. Активируйте репозиторий в Drone UI

3. Настройте триггеры:

   • Push в main → Production деплой
   • Push в develop → Staging деплой
   • Pull Request → Тестирование

Переменные окружения для CI/CD

# .drone.yml использует следующие секреты:
bot_token_staging      # Токен бота для staging
bot_token_production   # Токен бота для production
notification_webhook   # URL для уведомлений

📦 Docker Images

Development Image

• Тег: quiz-bot:dev
• Размер: ~200MB
• Использование: Локальная разработка

Production Image

• Тег: quiz-bot:latest
• Размер: ~150MB (multi-stage build)
• Оптимизации:
  • Multi-stage сборка
  • Непривилегированный пользователь
  • Health checks
  • Минимальный базовый образ

🔍 Мониторинг и логирование

Health Checks

Контейнер включает встроенные health checks:

# Проверка статуса
docker inspect --format='{{.State.Health.Status}}' quiz-bot

# Логи health check
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' quiz-bot

Логирование

# Development логи
docker-compose logs -f quiz-bot

# Production логи с ротацией
docker-compose -f docker-compose.prod.yml logs --tail=100 -f quiz-bot

# Системные логи контейнера
journalctl -u docker -f | grep quiz-bot

Мониторинг ресурсов

# Использование ресурсов
docker stats quiz-bot

# Непрерывный мониторинг
./scripts/deploy.sh monitor

🛠 Troubleshooting

Распространенные проблемы

1. Контейнер не запускается:

# Проверить логи
docker logs quiz-bot

# Проверить переменные окружения
docker inspect quiz-bot | grep -A 10 "Env"

2. База данных недоступна:

# Проверить volume
docker volume inspect quiz-test_quiz-bot-data

# Восстановить из backup
cp data/quiz_bot.db.backup.* data/quiz_bot.db

3. Pipeline падает:

# Проверить Drone логи
drone build logs repo/quiz-bot BUILD_NUMBER

# Локальное тестирование
./scripts/dev.sh test

Откат в случае проблем

# Production откат
./scripts/deploy.sh rollback

# Принудительный откат к конкретной версии
export IMAGE_TAG=previous-working-version
docker-compose -f docker-compose.prod.yml up -d

🔧 Настройка для разных сред

Development

# Используйте .env
BOT_TOKEN=dev_token
LOG_LEVEL=DEBUG

Staging

# Автоматически через CI/CD
# Использует bot_token_staging из Drone secrets

Production

# Создайте .env.prod
cp .env.prod.example .env.prod
# Заполните production значения

📚 Дополнительная информация

• Docker Best Practices
• Drone CI Documentation
• Docker Compose Reference

🤝 Contributing

При внесении изменений:

1. Создайте feature branch
2. Убедитесь, что тесты проходят локально
3. Создайте Pull Request
4. Pipeline автоматически протестирует изменения
5. После ревью изменения будут задеплоены