@@ -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
- 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.
Ansible-проект для автоматизации личного сервера. Плейбуки разворачивают докеризированные приложения (gitea, authelia, miniflux, wakapi, memos, outline, gramps, calibre, wanderer, remembos, transcriber и др.) через выделенных системных пользователей, Caddy-прокси и Yandex Docker Registry. Секреты управляются через Ansible Vault.
## 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)
- `task install-roles` — install galaxy roles into `galaxy.roles/ `
- `task ssh` — SSH to target using inventory ( `production.yml`
- `task btop` — run `btop` on remote .
- `task encrypt|decrypt -- <files>` — ansible-vault helpers .
- Authelia helpers:
- `task authelia-cli -- <args>` — run authelia CLI in docker .
- `task authelia-validate-config` — render `files/authelia/configuration.template.yml` with secrets and validate via authelia docker image .
- `task authelia-gen-random-string LEN=64` — generate random string .
- `task authelia-gen-secret-and-hash LEN=72` — generate hashed secret .
- `task format-py-files` — run Black via docker (pyfound/black) .
- `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`
## 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
- Local lint configs: `.yamllint.yml` , `.ansible-lint.yml` (excludes `.ansible/` , `.gitea/` , `galaxy.roles/` , `Taskfile.yml` ).
- CI (.gitea/workflows/lint.yml) installs `yamllint` and `ansible-lint` and runs `yamllint .` then `ansible-lint .` ; creates dummy vault file if missing.
- Pre-commit via lefthook (local hooks path): runs `gitleaks git --staged` and secret-file vault check script.
``` bash
uv sync
cp ansible-vault-password-file.dist ansible-vault-password-file
uv run ansible-galaxy install --role-file requirements.yml
```
## Coding/Templating Conventions
- 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` .
Требуется: `uv` , `ansible` , `yq` .
## Testing/Validation
- 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>` .
## Задачи (invoke)
## Operational Notes
- 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 `
- Backups: templates and scripts under `files/backups/` per service; `backup-all.py` orchestrates .
- Home network/DNS reference in README (Yandex domains) .
- Ensure `ansible-vault-password-file` present for vault operations and CI .
Таск-раннер — `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 с
- `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` .
av
