AGENTS.md

Project overview

Ansible infrastructure-as-code for mydns.gay, a public DNS service. No compiled source code — the repo is YAML playbooks, Jinja2 templates, config files, and a small PHP API.

Layout

All project content lives under ansible/. The root ~/ directory is an accidental artifact and can be ignored.

ansible/
  playbook.yml          # Main playbook (3 plays)
  inventory.example     # Sanitized inventory template
  inventory             # REAL inventory with secrets (gitignored but tracked)
  Makefile              # Build targets
  ansible.cfg           # Fact caching, nocows
  assets/               # Website files deployed to /var/www/site (HTML + PHP API)
  files/                # Jinja2 config templates for services
  tasks/                # Ansible task files
  handlers/             # Service restart/reload handlers

Host groups and roles

Group	Role
`dns_ord`	DNS resolver nodes — runs sdns (port 1053), Grafana Alloy
`lb_ord`	Load balancer — runs Blocky (port 53/853), Caddy (HTTPS/DoH), PHP API, Grafana Alloy

Commands

All commands run from ansible/:

make all       # Full deploy to all hosts
make dns       # Deploy only dns_ord group (--tags "dns")
make lb        # Deploy only lb_ord group (--tags "lb")
make website   # Deploy website only (--tags "website")

Underlying command: ansible-playbook playbook.yml -i inventory

Key details

Inventory contains secrets — ansible/inventory has real passwords (metrics_password). It is gitignored but currently tracked. Never commit changes to it without scrubbing secrets.
Config templates are Jinja2 — files in files/ reference hostvars, groups, and inventory variables. Validate template syntax when editing.
Metrics stack — Prometheus config is legacy (commented out in playbook). Current stack is Grafana Alloy forwarding to VictoriaMetrics (vm.put.gay) and Loki (loki.put.gay).
No tests or CI — no test suite, no CI pipeline. Verify changes by running targeted make targets against real infrastructure.
Ansible config — fact caching enabled (jsonfile at /tmp/ansible_facts_cache, 24h TTL).
PHP API — assets/api/ contains a hand-rolled PSR-7-like HTTP library. The API provides health checks and a custom router.

2.3 KiB Raw Blame History