rework

deploy/compose/README.md

@@ -0,0 +1,86 @@
+# Run fancy-dns outside Kubernetes
+
+This Compose deployment follows `deploy/k8s/00-config.yaml` and
+`deploy/k8s/10-deployment.yaml`. It builds the image from this checkout instead
+of pulling `registry.k6n.net/fancydns`, avoiding a bootstrap dependency on the
+cluster registry DNS.
+
+## Prepare and start
+
+From the repository root:
+
+```sh
+mkdir -p deploy/compose/{data,zones,rpz,tls}
+cp deploy/compose/.env.example deploy/compose/.env
+```
+
+Edit `deploy/compose/.env` (keep it private) and set a random API key as
+`FANCYDNS_API_KEY=<long-random-value>`. Install the certificate and private key
+for `dns.k6n.net` as `deploy/compose/tls/fullchain.pem` and
+`deploy/compose/tls/privkey.pem`. Add the same zone files used by the cluster to
+`deploy/compose/zones/`. Keep private key and `.env` out of source control.
+
+The container runs as UID/GID 65532 with a read-only root filesystem, so make
+the persistent directory writable first, for example:
+
+```sh
+sudo chown -R 65532:65532 deploy/compose/data
+docker compose --env-file deploy/compose/.env -f deploy/compose/compose.yaml build
+docker compose --env-file deploy/compose/.env -f deploy/compose/compose.yaml run --rm fancy-dns -config /etc/fancy-dns/config.yaml -check
+docker compose --env-file deploy/compose/.env -f deploy/compose/compose.yaml up -d
+```
+
+The DNS ports publish on all host interfaces: UDP/TCP 53, TCP 853, and TCP 443.
+The admin API is published only on `127.0.0.1:8080`; the embedded UI is disabled
+by default for backup-resolver use. To enable it, set `api.ui: true` in
+`config.yaml` and restart. Use an authenticated TLS reverse proxy for remote
+access. Check that nothing already owns host port
+53 before starting. The sample mounts TLS files and enables DoT and DoH, so the
+files must exist before startup.
+
+## How configuration is shared
+
+The repository is the source of truth, but there is currently **no automatic
+config distribution** between Kubernetes and the bare-metal Compose host.
+Kubernetes GitOps reconciles `deploy/k8s` from `main` (see `gitops/README.md`);
+the bare-metal host must get the updated checkout and have Compose restarted.
+Kubernetes gets its config from the ConfigMap in `deploy/k8s/00-config.yaml`;
+Compose reads the checked-in `deploy/compose/config.yaml` and files under
+`deploy/compose/`. Treat these as two deployment configs: commit reviewed
+changes to both when a shared resolver setting changes. The Compose config now
+includes the same `local.` forward zone to `10.10.0.1:53` as Kubernetes.
+
+The shared inputs to keep aligned are upstreams/forward zones, resolver policy,
+cache sizing/TTL, blocklist sources and actions, ACLs, local zone files, RPZ
+rules, and the DoT/DoH certificate for the same public DNS name. Deployment
+specific settings intentionally differ: listener container ports/storage paths
+must match each deployment, and Compose uses API-key auth with the UI disabled
+while Kubernetes uses OIDC. On bare metal the YAML, zone and RPZ files are
+bind-mounted; Kubernetes stores config, zones and RPZ in ConfigMaps and TLS in
+a Secret. Secrets should be provisioned separately on each system, not copied
+into Git. The Compose API key is in its private `.env` file.
+
+Do not share the `data/` directory or copy its bbolt files while either server
+is running. Cache snapshots and query logs are instance-local state. The
+managed zones written by the console also live under this directory; edits
+made on one instance do not appear on the other automatically. Make operator
+zone changes in the source of truth and deploy them to both, or designate one
+instance as the writer. Valkey clustering syncs cluster events/list leadership,
+not these files or bbolt state.
+
+The private forwarding target must remain reachable from both the Kubernetes
+pods and the bare-metal host. Verify that the bare-metal resolver has outbound
+access to its configured public upstreams before making it the cluster's
+registry resolver.
+
+For registry recovery, configure the Kubernetes nodes' OS resolver and the
+container runtime's registry DNS path to use this host's **static IP directly**
+as a DNS server (with another independent resolver as fallback). Do not rely on
+a hostname for the backup resolver, and do not make pulling this Compose image
+depend on `registry.k6n.net`: this Compose file builds the image locally from
+the repository checkout. A working route from the cluster nodes to the
+bare-metal host on UDP/TCP 53 is required; allow it through the host firewall.
+
+To update the local build after code changes, rebuild and recreate the
+container. The running server can hot-reload its YAML on SIGHUP, but Compose
+does not automatically send SIGHUP when bind-mounted files change.