pet-project-server/AGENTS.md

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

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.

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.