milestone 20: declarative configuration for iac

README.md

@@ -9,6 +9,8 @@ you what asked for what.
 
 - Blocklist filtering: subscribe to hosts/domain lists, plus your own allow
   and block rules with wildcard support (`*.example.com`)
+- Two configuration modes: a database the web UI edits, or a ZON file you keep
+  in git and converge onto at every start
 - Per-client policy groups: different filtering for the kids' tablet and
   your workstation
 - Local DNS records and conditional forwarding for internal zones
@@ -39,7 +41,7 @@ says what that signature does and does not prove.
 
 ## Quickstart (docker compose)
 
-Seed a minimal configuration and start the published image. This is what the
+Write a minimal configuration and start the published image. This is what the
 first release will make possible; it does not work today, because there is no
 image in the registry to pull:
 
@@ -60,11 +62,20 @@ The compose file defaults to `:latest`; pin a version for anything you intend
 to keep running. To run it before a release exists, build the image yourself and
 name it — `NXDNS_IMAGE=nxdns docker compose up -d` — as
 [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md)
-describes. DNS is on port 53, the web UI on <http://localhost:8080>. The config
-file seeds the database on first boot only; from then on the database is the
-truth and changes go through the UI, the API, or `nxdns export` /
-`nxdns import`. Full install instructions, including the systemd path and
-the Pi 5 recipe, are in
+describes. DNS is on port 53, the web UI on <http://localhost:8080>.
+
+The compose file runs `nxdns run --config=/etc/nxdns/config.zon`, which makes
+that file the configuration: every start reconciles the database onto it, and
+the UI refuses configuration edits. Edit the file and restart to change
+anything. Drop the `command:` line to run bare `nxdns run` instead, where the
+database is the configuration and changes go through the UI, the API, or
+`nxdns export` / `nxdns import` — the packaged systemd unit does that. Which
+mode is live is printed at every start (`authority: database` /
+`authority: file (<path>)`); see
+[docs/explanation/configuration-model.md](docs/explanation/configuration-model.md).
+
+Full install instructions, including the systemd path and the Pi 5 recipe, are
+in
 [docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md) and
 [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md).