# Единое приложение Hugo + Webhook

## 1. Концепция

### 1.1 Общая идея
Создание единого приложения на Go, которое объединяет webhook сервер и Hugo генератор статического сайта. Приложение обрабатывает Git webhook и автоматически пересобирает сайт при изменениях в репозитории.

### 1.2 Преимущества единого приложения
- **Простота развертывания**: Один контейнер вместо нескольких
- **Эффективность ресурсов**: Меньше накладных расходов
- **Простота мониторинга**: Единая точка наблюдения
- **Атомарность операций**: Все операции в одном процессе
- **Простота отладки**: Единый лог и контекст

### 1.3 Недостатки единого приложения
- **Менее гибкое масштабирование**: Сложность горизонтального масштабирования
- **Сложность при росте функциональности**: Монолитная архитектура
- **Единая точка отказа**: Все компоненты в одном процессе
- **Сложность обновлений**: Необходимость пересборки всего приложения

## 2. Архитектура

### 2.1 Компонентная диаграмма

```mermaid
graph TB
    A[Git Webhook] --> B[HTTP Server]
    B --> C[Webhook Handler]
    C --> D[Git Manager]
    D --> E[Hugo Builder]
    E --> F[Shared Volume]
    F --> G[Nginx]
    
    subgraph "Единое приложение"
        B
        C
        D
        E
    end
    
    subgraph "Внешние сервисы"
        A
        F
        G
    end
```

### 2.2 Структура приложения

**Основные модули:**
- **HTTP Server**: Обработка входящих запросов
- **Webhook Handler**: Валидация и обработка webhook
- **Git Manager**: Клонирование и обновление репозитория
- **Hugo Builder**: Сборка статического сайта
- **File Manager**: Управление файловой системой

## 3. Флоу обработки

### 3.1 Основной флоу

```mermaid
graph TB
    A[Получение webhook] --> B[Валидация подписи]
    B --> C[Проверка ветки]
    C --> D[Обновление репозитория]
    D --> E[Проверка изменений]
    E --> F[Сборка Hugo]
    F --> G[Автоматическое обновление статики]
    G --> H[Отправка уведомления]
    
    subgraph "Обработка ошибок"
        I[Retry логика]
        J[Fallback механизмы]
        K[Логирование ошибок]
    end
    
    E --> I
    F --> J
    G --> K
```

### 3.2 Детальный флоу

**Этап 1: Получение и валидация**
- Получение webhook от Git (GitHub, GitLab, Gitea)
- Валидация подписи webhook
- Проверка типа события (push, merge)
- Проверка целевой ветки

**Этап 2: Работа с репозиторием**
- Клонирование репозитория (если первый раз)
- Pull последних изменений
- Проверка наличия изменений в контенте
- Очистка временных файлов

**Этап 3: Сборка сайта**
- Проверка конфигурации Hugo
- Запуск Hugo сборки
- Обработка ошибок сборки
- Оптимизация статических файлов

**Этап 4: Развертывание**
- Автоматическое обновление файлов в общем volume
- Проверка целостности файлов
- Nginx автоматически раздает обновленный контент

**Этап 5: Уведомления**
- Отправка статуса в Telegram
- Логирование результата
- Обновление метрик

## 4. Конфигурация

### 4.1 Основные параметры

**Git настройки:**
- URL репозитория
- Ветка для отслеживания
- SSH ключи или токены
- Webhook секрет

**Hugo настройки:**
- Путь к исходникам
- Путь для сборки (общий volume)
- Конфигурационный файл
- Параметры оптимизации

**Системные настройки:**
- Пути для статических файлов
- Настройки логирования
- Общий volume для Hugo и Nginx

### 4.2 Переменные окружения

**Обязательные:**
- GIT_REPOSITORY_URL
- GIT_WEBHOOK_SECRET
- HUGO_SOURCE_PATH
- HUGO_OUTPUT_PATH
- SHARED_VOLUME_PATH

**Опциональные:**
- TELEGRAM_BOT_TOKEN
- TELEGRAM_CHAT_ID
- LOG_LEVEL
- METRICS_PORT

## 5. Обработка ошибок

### 5.1 Типы ошибок

**Git ошибки:**
- Недоступность репозитория
- Конфликты при merge
- Проблемы с аутентификацией
- Отсутствие изменений

**Hugo ошибки:**
- Ошибки в конфигурации
- Проблемы с шаблонами
- Ошибки в Markdown файлах
- Недостаток ресурсов

**Системные ошибки:**
- Проблемы с файловой системой
- Проблемы с общим volume
- Проблемы с сетью
- Недостаток места на диске

### 5.2 Стратегии восстановления

**Retry логика:**
- Автоматические повторные попытки
- Экспоненциальная задержка
- Максимальное количество попыток
- Graceful degradation

**Fallback механизмы:**
- Использование последней успешной сборки
- Откат к предыдущей версии
- Уведомления администратора
- Логирование для анализа

## 6. Мониторинг и метрики

### 6.1 Ключевые метрики

**Производительность:**
- Время обработки webhook
- Время сборки Hugo
- Размер генерируемых файлов
- Частота обновлений

**Надежность:**
- Количество успешных сборок
- Количество ошибок по типам
- Время восстановления
- Доступность сервиса

**Ресурсы:**
- Использование CPU
- Использование памяти
- Использование диска
- Сетевой трафик

### 6.2 Алерты

**Критические:**
- Сборка не завершилась в течение 5 минут
- Ошибки webhook валидации
- Проблемы с файловой системой
- Недоступность сайта

**Предупреждения:**
- Высокое время сборки
- Большой размер файлов
- Частые ошибки
- Низкое место на диске

## 7. Безопасность

### 7.1 Webhook безопасность
- Валидация подписи webhook
- Проверка IP адресов
- Rate limiting
- Логирование подозрительной активности

### 7.2 Системная безопасность
- Запуск от непривилегированного пользователя
- Ограничение доступа к файлам
- Шифрование чувствительных данных
- Регулярные обновления

### 7.3 Git безопасность
- Использование SSH ключей
- Проверка подписи коммитов
- Ограничение доступа к репозиторию
- Мониторинг изменений

## 8. Развертывание

### 8.1 Docker контейнер
- Многоэтапная сборка
- Минимальный образ на Alpine
- Включение Hugo и Git
- Оптимизация размера

### 8.2 Конфигурация
- Environment variables
- Конфигурационные файлы
- Volume mounts для данных
- Health checks

### 8.3 Orchestration
- Docker Compose для разработки
- Kubernetes для production
- Автоматическое масштабирование
- Rolling updates

## 9. Преимущества единого приложения

### 9.1 Операционные преимущества
- **Простота развертывания**: Один контейнер
- **Упрощенный мониторинг**: Единая точка наблюдения
- **Атомарность**: Все операции в одном процессе
- **Отладка**: Единый лог и контекст

### 9.2 Технические преимущества
- **Эффективность ресурсов**: Меньше накладных расходов
- **Производительность**: Прямая связь между компонентами
- **Надежность**: Меньше точек отказа
- **Безопасность**: Единая точка контроля

### 9.3 Преимущества разработки
- **Простота кода**: Единая кодовая база
- **Тестирование**: Интеграционные тесты
- **Версионирование**: Единая версия приложения
- **Документация**: Единая документация

## 10. Применимость

### 10.1 Идеальные сценарии
- Один пользователь или небольшая команда
- VPS с ограниченными ресурсами
- Простота развертывания важнее масштабируемости
- Быстрая итерация и отладка

### 10.2 Неподходящие сценарии
- Большие команды разработчиков
- Высокие требования к масштабируемости
- Сложная микросервисная архитектура
- Критически важные production системы