52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
|
# 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.
|