# Документация по сервису Certbot
*Последнее обновление: 3 декабря 2025 г.*

## Обзор

Сервис Certbot предназначен для автоматического получения и обновления SSL/TLS сертификатов Let's Encrypt для нескольких доменов в Docker-окружении. Сервис использует webroot-метод для подтверждения владения доменами и работает как автономный контейнер в составе Docker Compose стека.

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

### Основные компоненты

1. **Контейнер Certbot** (`certbot/certbot` образ)
2. **Конфигурационные файлы**:
   - `certbot.ini` - основные настройки Certbot
   - `init-certbot.sh` - скрипт инициализации и запуска
   - `checkRenewCerts.sh` - скрипт проверки и обновления сертификатов
   - Индивидуальные скрипты обновления для каждого домена
3. **Cron-задачи** для автоматического обновления
4. **Volumes** для хранения сертификатов и данных

### Поддерживаемые домены

Текущий список обслуживаемых доменов (декабрь 2025):

| Домен | Переменная окружения | Назначение |
|-------|---------------------|------------|
| `yalarba.ru` | `DOMAINS_yalarba` | Основной туристический портал |
| `valitovgaziz.ru` | `DOMAINS_valitovgaziz` | Персональный сайт |
| `easysite102.ru` | `DOMAINS_easysite102` | Сайт туроператора |
| `бегущийбашкир.рф` (IDN) | `DOMAINS_begushiybashkir` | Спортивный портал (кириллица) |
| `begushiybashkir.ru` | `DOMAINS_begushiybashkir_latin` | Спортивный портал (латиница) |

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

### Файлы конфигурации

#### `certbot.ini`
```ini
# Режим staging (используется для тестирования)
staging = False  # Для продакшена установить False

# Контактная информация
email = valitovgaziz@yandex.ru

# Согласие с условиями
agree-tos = True

# Неинтерактивный режим для автоматизации
non-interactive = True

# Путь для webroot-аутентификации
webroot-path = /var/www/certbot

# Настройки криптографии
key-type = ecdsa          # Использовать ECDSA ключи
elliptic-curve = secp384r1  # Кривая для ECDSA
```

#### `docker-compose.yml` (фрагмент для certbot)
```yaml
certbot:
  build:
    context: ./certbot
    dockerfile: Dockerfile
  container_name: certbot
  volumes:
    - ./certbot/config:/etc/letsencrypt/config
    - certbot_data:/etc/letsencrypt
    - certbot_www:/var/www/certbot
  env_file:
    - .env
  environment:
    - EMAIL=${EMAIL}
    - DOMAINS=${ALL_DOMAINS}
    - STAGING=0
  restart: unless-stopped
  healthcheck:
    test:
      [
        "CMD-SHELL",
        "test -f /etc/letsencrypt/live/$$(echo $${DOMAINS} | cut -d',' -f1)/fullchain.pem || exit 1",
      ]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s
```

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

Необходимые переменные в `.env` файле:

```bash
# Общие настройки
EMAIL=valitovgaziz@yandex.ru

# Списки доменов (через запятую)
DOMAINS_yalarba=yalarba.ru,www.yalarba.ru
DOMAINS_valitovgaziz=valitovgaziz.ru,www.valitovgaziz.ru
DOMAINS_easysite102=easysite102.ru,www.easysite102.ru
DOMAINS_begushiybashkir=бегущийбашкир.рф,www.бегущийбашкир.рф
DOMAINS_begushiybashkir_latin=begushiybashkir.ru,www.begushiybashkir.ru

# Агрегированный список для инициализации
ALL_DOMAINS=yalarba.ru,valitovgaziz.ru,easysite102.ru,бегущийбашкир.рф,begushiybashkir.ru
```

## Рабочий процесс

### 1. Инициализация (`init-certbot.sh`)

При запуске контейнера выполняются следующие шаги:

1. Проверка наличия сертификатов для каждого домена
2. Получение недостающих сертификатов через webroot-метод
3. Активация cron-демона
4. Настройка ежедневной проверки сертификатов
5. Запуск бесконечного процесса для поддержания работы контейнера

### 2. Ежедневная проверка (`checkRenewCerts.sh`)

Каждый день в 00:00 выполняется проверка всех сертификатов:

1. Проверяется срок действия каждого сертификата
2. Если до истечения осталось ≤ 2 дней, запускается процесс обновления
3. Используется индивидуальный скрипт для каждого домена

### 3. Обновление сертификатов

Индивидуальные скрипты обновления:
- `renewYalarbaCert.sh` - для yalarba.ru
- `renewValitovGazizCert.sh` - для valitovgaziz.ru
- `renewEasysite102.sh` - для easysite102.ru
- `renewBegushiyBashkir.sh` - для бегущийбашкир.рф
- `renewBegushiyBashkirLatin.sh` - для begushiybashkir.ru

## Мониторинг и логи

### Health Checks
- Certbot: проверка наличия файла `fullchain.pem` для первого домена
- Логи доступны через `docker logs certbot`

### Структура каталогов
```
/etc/letsencrypt/
├── live/
│   ├── yalarba.ru/
│   │   ├── cert.pem
│   │   ├── chain.pem
│   │   ├── fullchain.pem
│   │   └── privkey.pem
│   ├── valitovgaziz.ru/
│   └── ...
├── archive/           # Архивные версии сертификатов
└── renewal/          # Конфигурации обновления
```

## Расширение системы

### Добавление нового домена

1. **Добавить переменную окружения** в `.env` файл:
   ```bash
   DOMAINS_newdomain=newdomain.ru,www.newdomain.ru
   ```

2. **Обновить список всех доменов**:
   ```bash
   ALL_DOMAINS=existing.domains,newdomain.ru
   ```

3. **Создать скрипт обновления** (`renewNewdomainCert.sh`):
   ```bash
   #!/bin/sh
   echo "Получаем новые сертификаты для ${DOMAINS_newdomain}"
   certbot certonly --webroot \
       --config /etc/letsencrypt/config/certbot.ini \
       -w /var/www/certbot \
       -d ${DOMAINS_newdomain}
   ```

4. **Обновить `init-certbot.sh`**:
   ```bash
   # Проверяем наличие сертификатов для newdomain.ru
   if [ ! -d "/etc/letsencrypt/live/newdomain.ru" ]; then
     echo "Получаем новые сертификаты newdomain.ru ..."
     certbot certonly --webroot \
       --config /etc/letsencrypt/config/certbot.ini \
       -w /var/www/certbot \
       -d ${DOMAINS_newdomain}
   fi
   ```

5. **Обновить `checkRenewCerts.sh`**:
   Добавить новую функцию проверки и вызов в `main()`.

6. **Настроить nginx** для использования нового сертификата.

## Устранение неполадок

### Общие проблемы

1. **Ошибки при получении сертификатов**
   - Проверить доступность доменов из контейнера
   - Убедиться, что nginx обслуживает `.well-known/acme-challenge/`

2. **Сертификаты не обновляются**
   - Проверить логи cron: `docker exec certbot cat /var/log/cron`
   - Убедиться, что скрипты имеют права на выполнение

3. **Health check падает**
   - Проверить наличие сертификатов в `/etc/letsencrypt/live/`
   - Убедиться, что volumes правильно подключены

### Команды для диагностики

```bash
# Проверить статус контейнера
docker-compose ps certbot

# Посмотреть логи
docker logs certbot

# Проверить cron задачи
docker exec certbot crontab -l

# Проверить срок действия сертификата
docker exec certbot openssl x509 -in /etc/letsencrypt/live/yalarba.ru/cert.pem -noout -dates

# Запустить проверку вручную
docker exec certbot /opt/checkRenewCerts.sh
```

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

### Рекомендации

1. **Приватные ключи**: Хранятся в volume `certbot_data`, доступ только для certbot и nginx
2. **Staging режим**: Для тестирования установить `staging = True` в `certbot.ini`
3. **Ротация ключей**: Используется ECDSA с кривой secp384r1 для лучшей безопасности
4. **Ограничение доступа**: Контейнер не имеет открытых портов

### Резервное копирование

Рекомендуется регулярное копирование volume `certbot_data`:
```bash
# Создание бэкапа
docker run --rm -v certbot_data:/data -v $(pwd):/backup alpine tar czf /backup/certbot_backup_$(date +%Y%m%d).tar.gz -C /data .
```

## Часто задаваемые вопросы

**Q: Как часто обновляются сертификаты?**
A: Проверка выполняется ежедневно, обновление - за 2 дня до истечения срока.

**Q: Что делать при добавлении поддомена?**
A: Добавить поддомен в соответствующую переменную `DOMAINS_*` и перезапустить контейнер.

**Q: Как перейти с staging на production?**
A: Установить `staging = False` в `certbot.ini` и перезапустить контейнер.

**Q: Как проверить работу cron?**
A: `docker exec certbot crontab -l` покажет активные задачи.

## Контакты и поддержка

- Ответственный за обслуживание: Valitov Gaziz
- Email: valitovgaziz@yandex.ru
- Дата последнего обновления документации: 3 декабря 2025 г.

---

*Документация будет обновляться при добавлении новых доменов или изменении архитектуры системы.*