From 33de71a0878136af119344bee8dabd62ed47de0f Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Tue, 16 Dec 2025 19:29:52 +0300 Subject: [PATCH] Add agents.md file for ai agents --- .crushignore | 2 ++ AGENTS.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 .crushignore create mode 100644 AGENTS.md diff --git a/.crushignore b/.crushignore new file mode 100644 index 0000000..fd93f2d --- /dev/null +++ b/.crushignore @@ -0,0 +1,2 @@ +ansible-vault-password-file +*secrets.yml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5405d46 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# 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. + +## 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 -- ` — ansible-vault helpers. +- Authelia helpers: + - `task authelia-cli -- ` — 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). + +## 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-.yml`; grouped runs: `playbook-all-setup.yml`, `playbook-all-applications.yml`, `playbook-upgrade.yml`, etc. +- Secrets: encrypted `vars/secrets.yml`; additional `files//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. + +## 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`. + +## 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`. + +## 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.