Rewrite AGENTS.md

AGENTS.md

@@ -1,69 +1,135 @@
 # AGENTS GUIDE
 
-## Overview
+## Обзор
-Ansible-based server automation for personal services. Playbooks provision Dockerized apps (e.g., gitea, authelia, homepage, miniflux, wakapi, memos) via per-app users, Caddy proxy, and Yandex Docker Registry. Secrets are managed with Ansible Vault.
 
-## Project Layout
+Ansible-проект для автоматизации личного сервера. Плейбуки разворачивают докеризированные приложения (gitea, authelia, miniflux, wakapi, memos, outline, gramps, calibre, wanderer, remembos, transcriber и др.) через выделенных системных пользователей, Caddy-прокси и Yandex Docker Registry. Секреты управляются через Ansible Vault.
-- Playbooks: `playbook-*.yml` (per service), `playbook-all-*.yml` for grouped actions.
-- Inventory: `production.yml` (ungrouped host `server`).
-- Variables: `vars/*.yml` (app configs, images), secrets in `vars/secrets.yml` (vault-encrypted).
-- Roles: custom roles under `roles/` (e.g., `eget`, `owner`, `secrets`) plus galaxy roles fetched to `galaxy.roles/`.
-- Files/templates: service docker-compose and backup templates under `files/`, shared templates under `templates/`.
-- Scripts: helper Python scripts in `scripts/` (SMTP utilities) and `files/backups/backup-all.py`.
-- CI: `.gitea/workflows/lint.yml` runs yamllint and ansible-lint.
-- Hooks: `lefthook.yml` references local hooks in `/home/av/projects/private/git-hooks` (gitleaks, vault check).
-- Formatting: `.editorconfig` enforces LF, trailing newline, 4-space indent; YAML/Jinja use 2-space indent.
 
-## Setup
+## Структура проекта
-- Copy vault password sample: `cp ansible-vault-password-file.dist ansible-vault-password-file` (needed for ansible and CI).
-- Install galaxy roles: `ansible-galaxy role install --role-file requirements.yml --force` (or `task install-roles`).
-- Ensure `yq`, `task`, `ansible` installed per README requirements.
 
-## Tasks (taskfile)
+- `playbook-*.yml` — плейбуки по одному на сервис, `playbook-all-*.yml` для групповых запусков.
-- `task install-roles` — install galaxy roles into `galaxy.roles/`.
+- `production.yml` — инвентарь с единственным хостом `server`.
-- `task ssh` — SSH to target using inventory (`production.yml`).
+- `vars/*.yml` — переменные приложений и образов, `vars/secrets.yml` — зашифрованные секреты (vault).
-- `task btop` — run `btop` on remote.
+- `roles/` — кастомные роли (`eget`, `owner`, `secrets`), галактические роли в `galaxy.roles/`.
-- `task encrypt|decrypt -- <files>` — ansible-vault helpers.
+- `files/<app>/` — docker-compose шаблоны, конфиги, скрипты бэкапов для каждого сервиса.
-- Authelia helpers:
+- `templates/` — общие шаблоны (например `env.j2`).
-  - `task authelia-cli -- <args>` — run authelia CLI in docker.
+- `scripts/` — вспомогательные Python-скрипты (SMTP-утилиты для Yandex Cloud Postbox).
-  - `task authelia-validate-config` — render `files/authelia/configuration.template.yml` with secrets and validate via authelia docker image.
+- `.gitea/workflows/lint.yml` — CI: yamllint + ansible-lint.
-  - `task authelia-gen-random-string LEN=64` — generate random string.
+- `lefthook.yml` — pre-commit хуки (ruff, mypy, yamllint, ansible-lint, gitleaks, проверка vault).
-  - `task authelia-gen-secret-and-hash LEN=72` — generate hashed secret.
+- `tasks.py` — задачи через invoke (`inv <task>`).
-- `task format-py-files` — run Black via docker (pyfound/black).
+- `pyproject.toml` — зависимости Python, управляются через `uv`.
 
-## Ansible Usage
+## Настройка окружения
-- Inventory: `production.yml` with `server` host. `ansible.cfg` points to `./ansible-vault-password-file` and `./galaxy.roles` for roles path.
-- Typical deploy example (from README): `ansible-playbook -i production.yml --diff playbook-gitea.yml`.
-- Per-app playbooks: `playbook-<app>.yml`; grouped runs: `playbook-all-setup.yml`, `playbook-all-applications.yml`, `playbook-upgrade.yml`, etc.
-- Secrets: encrypted `vars/secrets.yml`; additional `files/<app>/secrets.yml` used for templating (e.g., Authelia). Respect `.crushignore` ignoring vault files.
-- Templates: many `docker-compose.template.yml` and `*.template.sh` files under `files/*` plus shared `templates/env.j2`. Use `vars/*.yml` to supply values.
-- Custom roles:
-  - `roles/eget`: installs `eget` tool; see defaults/vars for version/source.
-  - `roles/owner`: manages user/group and env template.
-  - `roles/secrets`: manages vault-related items.
 
-## Linting & CI
+```bash
-- Local lint configs: `.yamllint.yml`, `.ansible-lint.yml` (excludes `.ansible/`, `.gitea/`, `galaxy.roles/`, `Taskfile.yml`).
+uv sync
-- CI (.gitea/workflows/lint.yml) installs `yamllint` and `ansible-lint` and runs `yamllint .` then `ansible-lint .`; creates dummy vault file if missing.
+cp ansible-vault-password-file.dist ansible-vault-password-file
-- Pre-commit via lefthook (local hooks path): runs `gitleaks git --staged` and secret-file vault check script.
+uv run ansible-galaxy install --role-file requirements.yml
+```
 
-## Coding/Templating Conventions
+Требуется: `uv`, `ansible`, `yq`.
-- Indentation: 2 spaces for YAML/Jinja (`.editorconfig`), 4 spaces default elsewhere.
-- End-of-line: LF; ensure final newline.
-- Template suffixes `.template.yml`, `.yml.j2`, `.template.sh` are rendered via Ansible `template` module.
-- Avoid committing real secrets; `.crushignore` excludes `ansible-vault-password-file` and `*secrets.yml`.
-- Service directories under `files/` hold docker-compose and backup templates; ensure per-app users and registry settings align with `vars/*.yml`.
 
-## Testing/Validation
+## Задачи (invoke)
-- YAML lint: `yamllint .` (CI default).
-- Ansible lint: `ansible-lint .` (CI default).
-- Authelia config validation: `task authelia-validate-config` (renders with secrets then validates via docker).
-- Black formatting for Python helpers: `task format-py-files`.
-- Python types validation with mypy: `mypy <file.py>`.
 
-## Operational Notes
+Таск-раннер — `invoke` (файл `tasks.py`), вызывается через `inv`:
-- Deployments rely on `production.yml` inventory and per-app playbooks; run with `--diff` for visibility.
+
-- Yandex Docker Registry auth helper: `files/yandex-docker-registry-auth.sh`.
+- `inv pl -- <app> [app2 ...]` — запуск плейбука (`ansible-playbook -i production.yml --diff`).
-- Backups: templates and scripts under `files/backups/` per service; `backup-all.py` orchestrates.
+- `inv install-roles` — установка галактических ролей.
-- Home network/DNS reference in README (Yandex domains).
+- `inv ssh` — SSH на сервер.
-- Ensure `ansible-vault-password-file` present for vault operations and CI.
+- `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-gramps.yml` — генеалогия.
+- `playbook-calibre.yml` — управление электронными книгами.
+- `playbook-transcriber.yml` — транскрибация (образ из Yandex Registry).
+- `playbook-wanderer.yml` — пешие маршруты.
+- `playbook-remembos.yml` — интервальное повторение.
+
+### Агрегатные и служебные
+
+- `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`.