From ee61c24bb9fc019f63e1b1aa9f153c77194b691d Mon Sep 17 00:00:00 2001
From: Julian Cuni <julian.cuni@microservices.al>
Date: Tue, 7 Jul 2026 09:34:00 +0200
Subject: [PATCH] docs(wiki): Periphery v2.2.0 --user installer defaults
 root_directory=/etc/komodo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lab box (park-test) crash-looped: panic writing the agent key to
/etc/komodo/keys/periphery.key (Permission denied). Gotcha #9 was framed
as a hand-config hazard; v2.2.0's installer now writes the system-style
default even with --user. §7a: verify root_directory after every
install + sed fix + reset-failed/restart; user-unit vs sudo note; the
onboarding key survives a pre-connect crash.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
---
 wiki/decisions/appliance-provisioning.md | 12 ++++++++++--
 wiki/log.md                              | 10 ++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/wiki/decisions/appliance-provisioning.md b/wiki/decisions/appliance-provisioning.md
index fe1ebec..d907567 100644
--- a/wiki/decisions/appliance-provisioning.md
+++ b/wiki/decisions/appliance-provisioning.md
@@ -287,8 +287,16 @@ sudo loginctl enable-linger admin     # so the user service starts at boot witho
   NOT `:9120` — Core's container port `9120` is exposed-not-published; the agent reaches it through
   the proxy. (Gotcha #7 below.)
 - Config lands at `~/.config/komodo/periphery.config.toml`. The key field is **`core_address`**
-  (singular); `root_directory` must be a path `admin` can write (user-mode default is fine — a
-  `/etc/komodo` default from a system install would `Permission denied` for the user service).
+  (singular); `root_directory` must be a path `admin` can write. **⚠ VERIFY THIS after install —
+  Periphery v2.2.0's installer writes `root_directory = "/etc/komodo"` even with `--user`**
+  (bit the lab box 2026-07-07: panic `Failed to write private key pem to "/etc/komodo/keys/
+  periphery.key" … Permission denied`, crash-loop until systemd gives up). Fix + restart:
+  ```bash
+  sed -i 's|^root_directory = .*|root_directory = "'"$HOME"'/.komodo"|' ~/.config/komodo/periphery.config.toml
+  systemctl --user reset-failed periphery && systemctl --user restart periphery
+  ```
+  NB `sudo systemctl restart periphery` says *unit not found* — it's a USER unit; always
+  `systemctl --user …`. The onboarding key survives a pre-connect crash (unused until first dial).
 
 Verify: `systemctl --user status periphery` → active; the server **`park-buzi`** appears and goes
 **OK/green** in Core → Servers. Then **delete the onboarding key**.
diff --git a/wiki/log.md b/wiki/log.md
index 7c644b0..f3b5233 100644
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -2467,3 +2467,13 @@ Ubuntu's perl adduser/deluser tooling rejects the hyphenated username. [[applian
 §5c now uses `gpasswd -d <operator> sudo|lxd|lpadmin` (shadow-suite, no perl sanitize) and notes
 that group removal applies at NEXT login — the auto-login operator session keeps old memberships
 until reboot/relog, so verify `groups` from inside the session afterwards.
+
+## [2026-07-07] update | Periphery v2.2.0 --user installer writes /etc/komodo root_directory
+
+Lab test box (park-test): periphery crash-looped at startup — panic writing the private key to
+/etc/komodo/keys/periphery.key, Permission denied. Gotcha #9 was documented as a hand-config
+hazard, but v2.2.0's installer now DEFAULTS root_directory to /etc/komodo even with --user (the
+June park-buzi install defaulted under $HOME). [[appliance-provisioning]] §7a now says: verify
+root_directory after every install + the sed one-liner fix; also notes `sudo systemctl restart
+periphery` → "unit not found" (user unit) and that the single-use onboarding key survives a
+pre-connect crash.