# AGENTS GUIDE

## Обзор

Ansible-проект для автоматизации личного сервера. Плейбуки разворачивают докеризированные приложения (gitea, authelia, miniflux, wakapi, memos, outline, gramps, calibre, wanderer, remembos, transcriber и др.) через выделенных системных пользователей, Caddy-прокси и Yandex Docker Registry. Секреты управляются через Ansible Vault.

## Структура проекта

- `playbook-*.yml` — плейбуки по одному на сервис, `playbook-all-*.yml` для групповых запусков.
- `production.yml` — инвентарь с единственным хостом `server`.
- `vars/*.yml` — переменные приложений и образов, `vars/secrets.yml` — зашифрованные секреты (vault).
- `roles/` — кастомные роли (`eget`, `owner`, `secrets`), галактические роли в `galaxy.roles/`.
- `files/<app>/` — docker-compose шаблоны, конфиги, скрипты бэкапов для каждого сервиса.
- `templates/` — общие шаблоны (например `env.j2`).
- `scripts/` — вспомогательные Python-скрипты (SMTP-утилиты для Yandex Cloud Postbox).
- `.gitea/workflows/lint.yml` — CI: yamllint + ansible-lint.
- `lefthook.yml` — pre-commit хуки (ruff, mypy, yamllint, ansible-lint, gitleaks, проверка vault).
- `tasks.py` — задачи через invoke (`inv <task>`).
- `pyproject.toml` — зависимости Python, управляются через `uv`.

## Настройка окружения

```bash
uv sync
cp ansible-vault-password-file.dist ansible-vault-password-file
uv run ansible-galaxy install --role-file requirements.yml
```

Требуется: `uv`, `ansible`, `yq`.

## Задачи (invoke)

Таск-раннер — `invoke` (файл `tasks.py`), вызывается через `inv`:

- `inv pl -- <app> [app2 ...]` — запуск плейбука (`ansible-playbook -i production.yml --diff`).
- `inv install-roles` — установка галактических ролей.
- `inv ssh` — SSH на сервер.
- `inv zj` — zellij на удалённом сервере.
- `inv btop` — btop на удалённом сервере.
- `inv encrypt -- <file>` / `inv decrypt -- <file>` — шифрование/дешифрование через ansible-vault.
- `inv authelia-cli -- <args>` — запуск Authelia CLI в docker.
- `inv authelia-validate-config` — рендер и валидация конфига Authelia через docker.
- `inv authelia-gen-random-string LEN=10` — генерация случайной строки.
- `inv authelia-gen-secret-and-hash LEN=72` — генерация секрета и его хэша (pbkdf2-sha512).
- `inv format-py-files` — форматирование Python-файлов через Black (docker).

## Плейбуки

### Системные

- `playbook-system.yml` — базовая настройка системы (apt-пакеты, безопасность, fail2ban, монтирование хранилища).
- `playbook-docker.yml` — установка Docker CE, создание сетей (web_proxy_network, monitoring_network), cron очистки образов.
- `playbook-eget.yml` — установка eget и инструментов через него (rclone, restic, resticprofile, btop, gobackup, task, dust, zellij).
- `playbook-ufw.yml` — настройка файрвола UFW (SSH/22, Gitea SSH/2222, HTTP/80, HTTPS/443).
- `playbook-upgrade.yml` — обновление системных пакетов, очистка Docker.
- `playbook-backups.yml` — настройка restic-бэкапов и оркестратора backup-all.py с cron-расписанием.
- `playbook-caddyproxy.yml` — Caddy reverse proxy.

### Приложения

- `playbook-gitea.yml` — Git-сервер.
- `playbook-authelia.yml` — аутентификация/SSO.
- `playbook-miniflux.yml` — RSS-ридер.
- `playbook-wakapi.yml` — трекинг времени.
- `playbook-memos.yml` — заметки.
- `playbook-outline.yml` — вики/база знаний.
- `playbook-homepage.yml` — дашборд (образ из Yandex Registry).
- `playbook-rssbridge.yml` — RSS-агрегатор.
- `playbook-netdata.yml` — мониторинг.
- `playbook-dozzle.yml` — просмотр Docker-логов.
- `playbook-goaccess.yml` — аналитика веб-логов Caddy в реальном времени.
- `playbook-gramps.yml` — генеалогия.
- `playbook-calibre.yml` — управление электронными книгами.
- `playbook-transcriber.yml` — транскрибация (образ из Yandex Registry).
- `playbook-wanderer.yml` — пешие маршруты.
- `playbook-remembos.yml` — интервальное повторение.
- `playbook-tuwunel.yml` — Matrix-сервер (Tuwunel) с federation-делегацией на apex-домен.

### Агрегатные и служебные

- `playbook-all-setup.yml` — системная настройка целиком (system + docker + eget + backups).
- `playbook-all-applications.yml` — деплой всех приложений.
- `playbook-homepage-registry.yml` / `playbook-transcriber-registry.yml` — загрузка образов в Yandex Registry.
- `playbook-remove-user-and-app.yml` — удаление пользователя и приложения (`--extra-vars user_name=<name>`).

## Роли

- `roles/owner` — создаёт системного пользователя/группу для приложения, настраивает SSH-ключи, переменные окружения (~/.env, ~/.bashrc).
- `roles/eget` — скачивает и устанавливает утилиту eget.
- `roles/secrets` — управляет vault-зашифрованными файлами секретов для приложений.

Галактические роли (`galaxy.roles/`): `geerlingguy.security`, `geerlingguy.docker`, `yatesr.timezone`.

## Шаблоны и переменные

- Суффиксы шаблонов: `.template.yml`, `.yml.j2`, `.template.sh` — рендерятся Ansible модулем `template`.
- Большинство приложений определяют переменные inline в плейбуке. Отдельные файлы переменных только у homepage и transcriber (`vars/homepage.yml`, `vars/transcriber.yml` + `*.images.yml`).
- Общие переменные из `vars/secrets.yml`: `application_dir`, `bin_prefix`, `primary_user` и др.
- Каждое приложение: `app_name`, `app_user`, `app_owner_uid`, `app_owner_gid`, `base_dir`, `data_dir`.

## Линтинг и CI

- CI (`.gitea/workflows/lint.yml`): два параллельных job — yamllint и ansible-lint.
- Конфиги: `.yamllint.yml` (макс. длина строки 120), `.ansible-lint.yml` (профиль production, offline).
- Pre-commit хуки через lefthook:
  - `ruff format` + `ruff check` — форматирование и линтинг Python.
  - `mypy` — проверка типов Python.
  - `yamllint` — линтинг YAML.
  - `ansible-lint` — линтинг Ansible (профиль production).
  - `gitleaks` — поиск секретов в staged-файлах.
  - Проверка что секретные файлы зашифрованы vault.

## Соглашения по коду

- Отступы: 2 пробела для YAML/Jinja, 4 пробела в остальных файлах (`.editorconfig`).
- Окончания строк: LF, завершающий перевод строки обязателен.
- Не коммитить незашифрованные секреты; `.crushignore` исключает `ansible-vault-password-file` и `*secrets.yml`.
- Директории в `files/<app>/` содержат docker-compose и шаблоны бэкапов; пользователи и настройки реестра должны соответствовать `vars/*.yml`.

## Деплой

```bash
# Один сервис
inv pl -- gitea

# Несколько сервисов
inv pl -- gitea miniflux wakapi

# Напрямую через ansible-playbook
ansible-playbook -i production.yml --diff playbook-gitea.yml
```

## Бэкапы

- Шаблоны скриптов бэкапов в `files/<app>/` (backup.template.sh, gobackup.template.yml и др.).
- `files/backups/backup-all.py` — оркестратор, запускает все бэкапы через restic.
- Cron-расписание настраивается в `playbook-backups.yml`.