# Команды и сценарии

## CLI: letsencrypt-regru

Основные режимы:

- `--check` — проверить срок действия и тип (staging/production)
- `--info` — показать расширенную информацию по сертификату
- `--obtain` — принудительно получить production сертификат
- `--renew` — обновить существующий сертификат
- `--auto` — авто-режим: создать/обновить по необходимости

Тесты/диагностика:

- `--staging` — тестовый сертификат LE staging (без лимитов)
- `--test-cert` — самоподписанный тестовый сертификат (мгновенно, без интернета)
- `--test-api` — проверка API reg.ru (IP, баланс)
- `--test-dns` — полный цикл DNS TXT add → ожидание → nslookup → cleanup

Служебные (вызывает certbot):

- `--auth-hook`
- `--cleanup-hook`

Дополнительно:

- `-c/--config <file>` — путь к конфигу
- `-v/--verbose` — подробные логи
- `--force-cleanup` — очистка lock файлов certbot

### Мультидоменный режим

Если в конфиге указан `domains[]`, команды `--check/--info/--staging/--obtain/--renew/--auto/--test-*` будут выполняться **по всем доменам**.

## Makefile

Часто используемые команды:

- `make install` / `make uninstall`
- `make test-cert`
- `make obtain`
- `make renew`
- `make run` (аналог `--auto`)
- `make status`
- `make logs`

### CI / Wiki (workflow dispatch)

Эти команды **не выполняют деплой/синк локально** — они делают API запрос в Actions
на `gitea.example.com` и запускают соответствующий workflow.

- `make wiki-sync` — запустить синхронизацию `wiki/` в Wiki репозитория
- `make ci-release TAG=vX.Y.Z` (или `make ci-release VERSION=X.Y.Z`) — запустить релизный workflow
- `make deploy-service` (опционально `REF=branch_or_tag`) — запустить деплойный workflow

`wiki-sync` также запускается автоматически при push в `master`, если изменились файлы в `wiki/**`.

Нужно задать токен (любой из):

- `DFGIT_TOKEN` (предпочтительно)
- `GIT_TOKEN`
- `GITEA_TOKEN`
- `GITEA_ACCESS_TOKEN`

Примеры:

```bash
# Windows PowerShell
$env:DFGIT_TOKEN = "<token>"; make wiki-sync
$env:DFGIT_TOKEN = "<token>"; make ci-release TAG=v1.2.3
$env:DFGIT_TOKEN = "<token>"; make deploy-service
$env:DFGIT_TOKEN = "<token>"; make deploy-service REF=master
```

```bash
# Linux/macOS
DFGIT_TOKEN="<token>" make wiki-sync
DFGIT_TOKEN="<token>" make ci-release TAG=v1.2.3
DFGIT_TOKEN="<token>" make deploy-service
DFGIT_TOKEN="<token>" make deploy-service REF=master
```

Примечания:

- Базовый URL задаётся переменной `DFGIT_URL` (по умолчанию `https://gitea.example.com`).
- Репозиторий задаётся `DFGIT_REPO` (по умолчанию `your_username/configure_nginx_manager`).
- Для Linux/macOS требуется установленный `curl`.

## Типовой workflow (рекомендуется)

1) Подготовка
- `letsencrypt-regru --test-api -v`
- `letsencrypt-regru --test-dns -v`

2) Тестирование без лимитов
- `letsencrypt-regru --staging` **или** `letsencrypt-regru --test-cert`

3) Production
- `letsencrypt-regru --obtain`

4) Автопродление
- systemd timer или cron → `letsencrypt-regru --auto`

Если используете NPM — см. [Nginx_Proxy_Manager](Nginx_Proxy_Manager.md).


---

## Appendix (migrated from docs/CHEATSHEET.md)
<!-- MIGRATED_FROM_DOCS:CHEATSHEET.md -->

## ⚡ Шпаргалка по SSL сертификатам

### 🚀 Быстрый старт

#### Установка за 3 команды
```bash
sudo make install
sudo nano /etc/letsencrypt/regru_config.json  # Заполнить данные
sudo make test-cert                            # Тест
```

---

### 🧪 Тестирование (БЕЗ лимитов Let's Encrypt)

```bash
## Создать тестовый сертификат (неограниченно)
sudo make test-cert

## Проверить статус
sudo make status

## Просмотреть логи
sudo make logs
```

**Когда использовать:**
- ⚠️ Let's Encrypt: макс. 5 сертификатов/неделю
- ✅ Тестовые: НЕОГРАНИЧЕННО
- ⚡ Создание: 1-2 секунды vs 2-5 минут

---

### 🔒 Production (Let's Encrypt)

```bash
## Получить настоящий сертификат
sudo make obtain

## Автоматический режим (проверка + обновление)
sudo make run

## Принудительное обновление
sudo make renew
```

---

### 📋 Основные команды

#### Команды letsencrypt-regru

| Команда | Описание | Лимиты | Использование |
|---------|----------|--------|---------------|
| `--check` | Проверить срок действия | - | Мониторинг |
| `--obtain` | Получить новый сертификат | ⚠️ 5/неделю | Первое создание |
| `--renew` | Обновить существующий | ⚠️ 5/неделю | Продление |
| `--auto` | Авто-проверка и обновление | ⚠️ 5/неделю | Cron/systemd |
| `--test-cert` | Тестовый сертификат | ✅ Нет | Разработка |
| `--test-api` | Проверить API reg.ru | - | Диагностика |
| `--test-dns` | Тест создания DNS записи | - | Проверка перед SSL |
| `--help` | Справка | - | Помощь |
| `-v` | Подробный вывод | - | Отладка |

#### Команды Makefile

| Команда | Описание | Эквивалент |
|---------|----------|------------|
| `make test-cert` | Тестовый сертификат | `letsencrypt-regru --test-cert` |
| `make obtain` | Let's Encrypt новый | `letsencrypt-regru --obtain` |
| `make renew` | Обновить существующий | `letsencrypt-regru --renew` |
| `make run` | Авто-режим | `letsencrypt-regru --auto` |
| `make status` | Статус системы | - |
| `make logs` | Показать логи | `journalctl -u letsencrypt-regru` |
| `make check-config` | Проверить конфигурацию | - |

#### Команды letsencrypt_regru.sh

| Команда | Описание |
|---------|----------|
| `sudo bash letsencrypt_regru.sh install` | Установить приложение |
| `sudo bash letsencrypt_regru.sh update` | Обновить приложение |
| `sudo bash letsencrypt_regru.sh uninstall` | Удалить приложение |

---

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

#### Минимальная (тестирование)
```json
{
    "domain": "test.example.com",
    "wildcard": true,
    "cert_dir": "/etc/letsencrypt/live"
}
```

#### Полная (production + NPM)
```json
{
    "regru_username": "myuser",
    "regru_password": "mypassword",
    "domain": "example.com",
    "wildcard": true,
    "email": "admin@example.com",
    "renewal_days": 30,
    "npm_enabled": true,
    "npm_host": "https://npm.example.com",
    "npm_email": "admin@example.com",
    "npm_password": "npm_password"
}
```

---

### 🔄 Workflow

#### Разработка → Production

```bash
## 1. Разработка (тестовые сертификаты)
sudo make test-cert              # Создать тестовый
## Тестировать приложение...

## 2. Production (Let's Encrypt)
sudo rm -rf /etc/letsencrypt/live/example.com/  # Удалить тест
sudo make obtain                 # Создать production
```

---

### 📁 Важные пути

```bash
## Конфигурация
/etc/letsencrypt/regru_config.json

## Сертификаты
/etc/letsencrypt/live/example.com/
├── privkey.pem      # Приватный ключ
├── cert.pem         # Сертификат
├── fullchain.pem    # Полная цепочка (для nginx)
└── chain.pem        # CA цепочка

## Скрипты
/opt/letsencrypt-regru/letsencrypt_regru_api.py

## Логи
/var/log/letsencrypt_regru.log
```

---

### 🔍 Проверка

```bash
## Проверить конфигурацию
sudo make check-config

## Проверить сертификат
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -text -noout

## Проверить срок действия
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -dates

## Проверить systemd
sudo systemctl status letsencrypt-regru.timer
sudo systemctl list-timers letsencrypt-regru.timer

## Проверить cron
sudo crontab -l | grep letsencrypt
```

---

### 🐛 Отладка

```bash
## Подробные логи
sudo make logs

## Тестовый запуск с подробностями
sudo python3 /opt/letsencrypt-regru/letsencrypt_regru_api.py \
    -c /etc/letsencrypt/regru_config.json --check -v

## Логи certbot
sudo tail -f /var/log/letsencrypt/letsencrypt.log

## Логи systemd
sudo journalctl -u letsencrypt-regru.service -f
```

---

### ⚠️ Частые ошибки

#### Let's Encrypt: Rate limit exceeded
```bash
## РЕШЕНИЕ: Используйте тестовые сертификаты
sudo make test-cert
```

#### NPM: Certificate not found
```bash
## РЕШЕНИЕ: Проверьте настройки NPM
sudo make check-config

## Проверьте подключение
curl -k https://npm.example.com
```

#### Permission denied
```bash
## РЕШЕНИЕ: Запускайте с sudo
sudo make test-cert
```

---

### 🎯 Сценарии использования

#### Локальная разработка
```bash
sudo make test-cert
## Открыть https://localhost (игнорировать предупреждение)
```

#### CI/CD тестирование
```bash
## В pipeline
sudo make test-cert
## Запустить тесты...
sudo make status
```

#### Staging окружение
```bash
sudo make test-cert  # Или
sudo make obtain     # Если есть домен
```

#### Production окружение
```bash
sudo make install
sudo make obtain
## Автоматическое обновление через cron/systemd
```

---

### 📚 Документация

- **README.md** - Полное руководство (1420+ строк)
- **TESTING_GUIDE.md** - Тестирование (370+ строк)
- **PROJECT_STRUCTURE.md** - Структура проекта
- **CHEATSHEET.md** - Эта шпаргалка

---

### 🆘 Быстрая помощь

```bash
## Показать все команды
make help

## Проверить установку
sudo make status

## Полная переустановка
sudo make uninstall
sudo make install
```

---

### 💡 Советы

1. **Всегда начинайте с тестовых сертификатов** - избегайте лимитов
2. **Проверяйте конфигурацию** - `make check-config`
3. **Мониторьте логи** - `make logs`
4. **Автоматизируйте** - systemd/cron уже настроены
5. **Храните бэкапы** конфигурации

---

**Версия**: 2.1  
**Обновлено**: 27.10.2025



---

## Appendix (migrated from docs/MAKEFILE_COMMANDS.md)
<!-- MIGRATED_FROM_DOCS:MAKEFILE_COMMANDS.md -->

## Makefile Commands - Quick Reference

### 📋 Категории команд

#### 🛠️ Установка и развертывание

```bash
make install              # Полная установка приложения
make uninstall           # Удаление приложения
make status              # Проверка статуса установки
make check-config        # Проверка конфигурации
```

#### 🔨 Сборка исполняемых файлов

```bash
make build               # Собрать для текущей ОС
make build-linux         # Собрать для Linux
make build-windows       # Собрать для Windows
make build-all           # Собрать для всех платформ
```

#### 📦 Создание пакетов

```bash
make package-linux       # Создать tar.gz для Linux
make package-windows     # Создать zip для Windows
make release             # Полный цикл релиза
```

#### 🧪 Тестирование

```bash
make test-run            # Тестовый запуск скрипта
make test-cert           # Создать тестовый сертификат
make test-build          # Протестировать собранный файл
```

#### 🚀 Запуск операций

```bash
make run                 # Автоматическая проверка и обновление
make obtain              # Получить новый сертификат
make renew               # Обновить существующий сертификат
```

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

```bash
make logs                # Показать логи
make status              # Статус служб
```

#### 🧹 Очистка

```bash
make clean               # Очистить временные файлы Python
make clean-build         # Очистить артефакты сборки
```

#### ℹ️ Информация

```bash
make help                # Показать справку
make build-info          # Информация о среде сборки
```

---

### 🎯 Типовые сценарии

#### Первоначальная установка
```bash
sudo make install
sudo make check-config
sudo make test-run
```

#### Сборка релиза для GitHub
```bash
make clean-build
make release
## Файлы будут в dist/
```

#### Создание тестового окружения
```bash
sudo make install
sudo make test-cert
sudo make status
```

#### Обновление сертификата вручную
```bash
sudo make run
sudo make logs
```

#### Удаление приложения
```bash
sudo make uninstall
```

---

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

Основные переменные определены в Makefile:

```makefile
INSTALL_DIR = /opt/letsencrypt-regru
CONFIG_FILE = /etc/letsencrypt/regru_config.json
LOG_FILE = /var/log/letsencrypt_regru.log
SERVICE_NAME = letsencrypt-regru
PYTHON = python3
```

---

### 🔐 Требуемые права

**Требуют sudo:**
- `make install`
- `make uninstall`
- `make run`
- `make obtain`
- `make renew`
- `make test-run`
- `make test-cert`

**Не требуют sudo:**
- `make build*`
- `make package*`
- `make clean*`
- `make help`
- `make build-info`

---

### 💡 Полезные комбинации

```bash
## Полная переустановка
sudo make uninstall && sudo make install

## Сборка и тестирование
make build && make test-build

## Очистка и релиз
make clean-build && make release

## Проверка после установки
sudo make status && sudo make test-run && sudo make logs
```