Match the Kanidm server to the CLI, and say why a token failed

Three things in one setup run, two of them mine.

The server image was 1.11.1 while the host's CLI is 1.11.2, and a
1.11.2 client looks up the domain entry at a UUID 1.11.1 does not
have. So `system domain set-displayname` and `set-image` both failed
with "Item not found", which says nothing about versions. The CLI had
been warning about the mismatch on every single call. Image bumped to
1.11.2; the README says to keep them together and which one to move.

The onboarding token asked for `--rw`, and the flag is spelled
`--readwrite`. The script swallowed stderr and reported a bare warning,
so a step that leaves every invite failing closed said nothing about
why. It now passes the right flag, and if it still fails it says what
the CLI said and prints the command to retry by hand.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -157,3 +157,17 @@ decisions rather than branding:
   it is still a door, so it is turned on knowingly or not at all.
 - `system domain set-allow-easter-eggs` - seasonal icons and birthday
   surprises. Off in production builds, and this is somebody's vel.
+
+## Keep the CLI and the server on the same version
+
+The `kanidm` CLI on the host and the `kanidm/server` image in
+`compose.yml` must match. They are not merely fussy about it: a 1.11.2
+client against a 1.11.1 server looks up the domain entry at a UUID the
+older server does not have, so `system domain set-displayname` and
+`set-image` fail with "Item not found" - a message that says nothing
+about versions. The CLI warns on every call; the warning is worth
+reading.
+
+The host's CLI comes from pacman and moves on its own, so the image is
+what to bump: `image: kanidm/server:<version>` in `compose.yml`, then
+`podman compose up -d kanidm`.

compose.yml

@@ -59,7 +59,7 @@ services:
       retries: 3
 
   kanidm:
-    image: kanidm/server:1.11.1
+    image: kanidm/server:1.11.2
     restart: unless-stopped
     environment:
       KANIDM_CONFIG_PATH: /data/server.toml

kanidm-setup.sh

@@ -78,14 +78,20 @@ if ! $K service-account get $SA >/dev/null 2>&1; then
   $K group add-members idm_people_pii_read $SA || true
 fi
 if ! grep -q '^KANIDM_API_TOKEN=.' portal.env 2>/dev/null; then
-  token=$($K service-account api-token generate $SA "portal" --rw 2>/dev/null | tail -1)
+  token=$($K service-account api-token generate $SA "portal" --readwrite | tail -1)
   if [ -n "$token" ]; then
     grep -q '^KANIDM_API_TOKEN=' portal.env \
       && sed -i "s|^KANIDM_API_TOKEN=.*|KANIDM_API_TOKEN=$token|" portal.env \
       || printf 'KANIDM_API_TOKEN=%s\n' "$token" >> portal.env
     echo "onboarding token written to portal.env"
   else
-    echo "warning: could not generate the onboarding token - invites will fail closed until it is set"
+    # Loudly, and with whatever the CLI said: the first version of this
+    # passed `--rw` for a flag that is spelled `--readwrite`, swallowed
+    # the error, and reported a bare warning that said nothing about
+    # why. A step that leaves invites broken should not be quiet about
+    # how it failed.
+    echo "warning: could not generate the onboarding token - invites will fail closed until it is set" >&2
+    echo "  retry by hand:  $K service-account api-token generate $SA portal --readwrite" >&2
   fi
 fi