# Инструкция: выпуск сертификата Let's Encrypt (DNS-01)

Универсальная инструкция для использования как промпт в следующих проектах. Подходит, когда HTTP-01 недоступен (порт 80 закрыт, блокировки, инстанс за NAT).

---

## Когда использовать DNS-01

- **HTTP-01** не срабатывает: таймаут, «Connection refused», порт 80 недоступен с интернета, провайдер или регион блокирует запросы от Let's Encrypt.
- **DNS-01**: проверка владения доменом по TXT-записи `_acme-challenge.<домен>`. До сервера стучаться не нужно — важен только DNS.

---

## Общий алгоритм

1. Выбрать DNS-провайдера домена и проверить, есть ли у него API или плагин для certbot/acme.sh.
2. Установить certbot и плагин для этого DNS (или использовать acme.sh с DNS API).
3. Создать файл учётных данных (логин/API-токен провайдера), права 600.
4. Запросить сертификат: `certbot certonly --authenticator dns-<провайдер> ... -d example.com`.
5. Подложить полученные `fullchain.pem` и `privkey.pem` в reverse proxy (Nginx Proxy Manager, nginx, Caddy и т.д.).
6. Настроить автообновление (systemd timer certbot + deploy-hook при продлении).

---

## Пример: Beget.com (certbot-dns-beget-api)

**Условия:** домен на Beget, доступ к API (логин + пароль или отдельный API-пароль).

1. **Установка (Debian/Ubuntu):**
   ```bash
   apt install certbot
   pip3 install certbot-dns-beget-api   # или: python3 -m pip install certbot-dns-beget-api --break-system-packages
   ```

2. **Файл учётных данных** (например `/root/.secrets/certbot/beget.ini`):
   ```ini
   dns_beget_api_username = ВАШ_ЛОГИН_BEGET
   dns_beget_api_password = ВАШ_ПАРОЛЬ_ИЛИ_API_ПАРОЛЬ
   ```
   ```bash
   chmod 600 /root/.secrets/certbot/beget.ini
   ```

   **Homelab (Vaultwarden):** креды хранятся в Vaultwarden (объект **beget**). Деплой с хоста Proxmox:
   ```bash
   /root/scripts/deploy-beget-credentials.sh
   ```
   Скрипт генерирует `beget.ini` из Vaultwarden, атомарно пушит в CT 100, ставит права 600 и pre-hook проверки. **Ротация:** сменил пароль в Vaultwarden → запустил `deploy-beget-credentials.sh` → готово.

3. **Запрос сертификата:**
   ```bash
   certbot certonly \
     --authenticator dns-beget-api \
     --dns-beget-api-credentials /root/.secrets/certbot/beget.ini \
     --dns-beget-api-propagation-seconds 120 \
     -d example.com \
     --non-interactive \
     --agree-tos \
     --email your@email.com
   ```

4. **Где лежат файлы после выпуска:**
   - Сертификат: `/etc/letsencrypt/live/<домен>/fullchain.pem`
   - Ключ: `/etc/letsencrypt/live/<домен>/privkey.pem`

5. **Интеграция с Nginx Proxy Manager (NPM):**
   - Либо вручную скопировать в каталог custom_ssl (например `custom_ssl/npm-<id>/fullchain.pem` и `privkey.pem`) и перезагрузить nginx в контейнере NPM.
   - Либо добавить запись в БД NPM (таблица `certificate`, provider `other`) и положить те же файлы в каталог, на который ссылается конфиг nginx (например `custom_ssl/npm-<certificate_id>/`).

6. **Продление и deploy-hook** (чтобы после `certbot renew` сертификат автоматически подхватывался NPM):
   ```bash
   # /etc/letsencrypt/renewal-hooks/deploy/copy-to-npm.sh
   # RENEWED_LINEAGE = путь к обновлённому сертификату, например /etc/letsencrypt/live/example.com
   if [ "$RENEWED_LINEAGE" = "/etc/letsencrypt/live/EXAMPLE_DOMAIN" ]; then
     cp "$RENEWED_LINEAGE/fullchain.pem" /path/to/npm/custom_ssl/npm-ID/
     cp "$RENEWED_LINEAGE/privkey.pem"  /path/to/npm/custom_ssl/npm-ID/
     chmod 644 /path/to/npm/custom_ssl/npm-ID/fullchain.pem
     chmod 600 /path/to/npm/custom_ssl/npm-ID/privkey.pem
     docker exec CONTAINER_NPM nginx -s reload
   fi
   ```
   Сделать скрипт исполняемым: `chmod +x ...`

7. **Проверка автообновления:** таймер certbot обычно уже включён:
   ```bash
   systemctl list-timers | grep certbot
   ```

---

## Другие DNS-провайдеры (идеи для промпта)

- **Cloudflare:** `certbot-dns-cloudflare`, переменные `dns_cloudflare_api_token` или `dns_cloudflare_email` + `dns_cloudflare_api_key`.
- **Reg.ru:** плагин `certbot-dns-regru`, свои переменные в credentials-файле.
- **NIC.ru:** `certbot-dns-nicru`.
- **Без API:** `certbot certonly --manual --preferred-challenges dns -d example.com` — выводит TXT-значение, пользователь вручную добавляет запись в DNS, затем продолжает по Enter.

---

## Краткий чеклист для нового домена/проекта

- [ ] Домен и DNS у одного провайдера; выяснить, есть ли API/плагин для ACME DNS-01.
- [ ] Установить certbot и нужный DNS-плагин.
- [ ] Создать credentials-файл (chmod 600), не коммитить в git.
- [ ] Выпустить сертификат: `certbot certonly --authenticator dns-... -d domain`.
- [ ] Подложить fullchain.pem и privkey.pem в reverse proxy.
- [ ] Добавить deploy-hook для продления и перезагрузки nginx/прокси.
- [ ] Убедиться, что certbot.timer включён для автоматического renew.