deploy: the compose file names its own release, and the cut moves it with the version

docs/how-to/upgrade.md

@@ -168,20 +168,36 @@ journalctl -u nxdns -f
 
 ### Docker
 
+The compose file names the release it belongs to, so upgrading the image is upgrading the file. A new release's compose file can change more than the image — the `command:` line or a port — so both ways below replace yours: if you edited it by hand, carry your edits over to the new one. To keep your own file as it is, skip the `curl` or the `git checkout` and set `NXDNS_VERSION=$VERSION` on the `pull` and `up` lines instead: it overrides the release the file names. A compose file from `v0.0.22` or earlier defaults to `:latest`, so with one of those the variable is needed on both lines, or `pull` and `up` can land on different images if a release happens between them.
+
+With the single downloaded file of [Install with Docker](install-with-docker.md), fetch the new release's copy over it in its directory, then pull and recreate:
+
 ```sh
-NXDNS_VERSION=$VERSION docker compose -f deploy/docker/compose.yaml pull
-NXDNS_VERSION=$VERSION docker compose -f deploy/docker/compose.yaml up -d
+cd ~/nxdns
+curl -fLO "$BASE/raw/tag/v$VERSION/deploy/docker/compose.yaml"
+docker compose pull
+docker compose up -d
+```
+
+With a checkout of the repository, fetch the tag and move to it, from the repository root:
+
+```sh
+git fetch origin tag "v$VERSION"
+git checkout "v$VERSION"
+docker compose -f deploy/docker/compose.yaml pull
+docker compose -f deploy/docker/compose.yaml up -d
 ```
 
 Compose recreates the container against the same `nxdns-data` volume. What happens to the file in `etc-nxdns` depends on the `command:` in your compose file: with the shipped `run --config=/etc/nxdns/config.zon` the file is the configuration and the restart reconciles onto it; without it, the database in the volume is the configuration and the file is read by nothing.
 
-Set `NXDNS_VERSION` on both lines, or export it. Without it the compose file falls back to `:latest`, and `pull` and `up` could then land on different images if a release happens between them.
-
-> Not run on this host: `pull` needs a published image, and there is none.
-> What was run is `docker compose -f deploy/docker/compose.yaml config`, which
-> resolves the variables without contacting a registry: `NXDNS_VERSION=0.0.1`
-> gave `image: git.mial.net/mokhtar/nxdns:0.0.1`, and no variable at all gave
-> `:latest`.
+> Not run on this host: `pull` and `up` were not run against a new release.
+> What was run on 2026-10-20 is `docker compose -f deploy/docker/compose.yaml
+> config` on a tree whose `build.zig.zon` declares `0.0.22`, which resolves
+> the variables without contacting a registry: no variable gave
+> `image: git.mial.net/mokhtar/nxdns:0.0.22`, and `NXDNS_VERSION=0.0.21` gave
+> `image: git.mial.net/mokhtar/nxdns:0.0.21`.
+> The fetch half was run the same day against `v0.0.22`: the `curl` URL
+> returned 200, and `git fetch --dry-run origin tag v0.0.22` exited 0.
 
 ## 4. Confirm the upgrade