noot

AGENTS.md

@@ -0,0 +1,51 @@
+# 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/`:
+
+```sh
+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.

ansible/assets/index.html

@@ -108,7 +108,7 @@
           i'm really lazy, so the truth is, this is made from patching together a bunch of open source tools
           <ul>
             <li><a href="https://github.com/caddyserver/caddy">caddy (https routing, H3)</a></li>
-            <li><a href="https://github.com/PowerDNS/pdns">dnsdist (dns load balancer)</a></li>
+            <li><a href="https://github.com/0xERR0R/blocky">blocky (dns proxy/cache)</a></li>
             <li><a href="https://github.com/semihalev/sdns">sdns (recursive resolver)</a></li>
             <li><a href="https://github.com/ansible/ansible">ansible (setup & config management)</a></li>
             <li><a href="https://debian.org">debian (host)</a></li>