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