pet-project-server/AGENTS.md

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.

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

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-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.

Деплой

# Один сервис
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.