docs: README, changelog, contributing, security, deployment, operations, CI

README.md

@@ -0,0 +1,72 @@
+# dns-traefik-sync
+
+Automatic DNS registration for Traefik-managed containers using Kerberos-authenticated
+RFC 2136 dynamic updates against a Samba Active Directory DNS server.
+
+Polls the Traefik API, extracts Host() rules from docker-provider routers, and
+creates/removes A records in Samba AD DNS using GSS-TSIG authentication.
+No SSH. No passwords. No broad privilege.
+
+## How it works
+
+    Traefik API (/api/http/routers)
+        └── docker provider routers with Host() rules
+                └── filtered to target zone
+                        └── diff against last known state
+                                └── nsupdate -g (GSS-TSIG via Kerberos keytab)
+                                        └── Samba AD DNS (vetinari)
+
+On each poll cycle:
+
+- Fetches all routers from the Traefik API
+- Filters to docker provider only, extracts hostnames matching the target zone
+- Compares against state from the previous cycle
+- Adds A records for new hostnames, removes A records for gone hostnames
+- Renews the Kerberos ticket before each cycle
+
+## Requirements
+
+- Traefik with API enabled
+- Samba AD DC with a service account in DnsAdmins
+- Keytab for the service account stored as a Docker secret
+- Docker Swarm mode (for secrets)
+
+## Configuration
+
+All configuration via environment variables:
+
+| Variable         | Default                            | Description                        |
+|------------------|------------------------------------|------------------------------------|
+| TRAEFIK_API      | http://192.168.88.2:8080           | Traefik API base URL               |
+| DNS_SERVER       | 192.168.88.1                       | Samba AD DNS server IP             |
+| DNS_ZONE         | ankh-morpork.discworld.network     | Zone to manage records in          |
+| TARGET_IP        | 192.168.88.2                       | IP address for created A records   |
+| TTL              | 300                                | TTL for created records (seconds)  |
+| POLL_INTERVAL    | 60                                 | Poll interval (seconds)            |
+| KEYTAB           | /run/secrets/dns-updater-keytab    | Path to Kerberos keytab            |
+| KRB_PRINCIPAL    | dns-updater@DISCWORLD.NETWORK      | Kerberos principal                 |
+| STATE_FILE       | /tmp/dns_state.json                | State persistence path             |
+
+## Deployment
+
+See docs/deployment.md for full setup instructions.
+See docs/operations.md for day-to-day operational guidance.
+
+## Security model
+
+- Service account scoped to DnsAdmins only
+- Keytab stored as a Docker secret, never on disk
+- GSS-TSIG: Kerberos mutual authentication, updates signed and verified by the KDC
+- No SSH, no HTTP webhooks, no plaintext credentials
+- Container runs as nobody
+
+## Limitations
+
+- A records only (no CNAME, no AAAA)
+- Single target IP (all records point to the same host)
+- Single zone
+- On restart, re-syncs from Traefik - safe and idempotent
+
+## Changelog
+
+See CHANGELOG.md