Initial commit: Hermes skill xmpp-server-prosody

references/prosody-012-upgrade-path.md

@@ -0,0 +1,64 @@
+# Prosody 0.12 upgrade path — docker images, what it fixes, risks (2026-08-29)
+
+Status: **0.12.6 is the current stable Prosody release, but there is NO official
+docker image tag for it.** Upgrading from 0.11.9 fixes two standing problems on
+nixg.ru at once: XEP-0356 privileged-entity for the bridge, and UnifiedPush
+(`util.jwt` only exists in 0.12+).
+
+## Docker image situation (verified via registry API + pulls)
+
+| Source | Tag | Version | Verdict |
+|---|---|---|---|
+| `prosody/prosody` (official) | `latest` | **0.11.9** (stale) | official tags stop at 0.11.x; no 0.12 tag exists |
+| `prosody/prosody` (official) | `trunk` | unreleased trunk | unstable, not for prod |
+| `prosodyim/prosody` (3rd party) | `0.12` | nightly build 236 (2026-04-29) | nightly — NOT a stable release |
+| `prosodyim/prosody` (3rd party) | `13.0` | nightly build 98 (2026-06-07) | nightly of next major — no |
+| build-your-own | from `https://prosody.im/downloads/source/prosody-0.12.6.tar.gz` (HTTP 200) | **0.12.6 stable** | the correct path |
+
+So `docker pull prosody/prosody:0.12` → `not found`, `prosodyim/prosody:0.12.6`
+→ `not found`, `prosodyim/prosody:0.12` exists but is a **nightly** — do not run
+nightlies in prod. Only route to a stable 0.12: build a custom image on top of
+`prosody/prosody:0.11.9` compiling/installing the 0.12.6 tarball, and re-test.
+
+## What the 0.11 → 0.12 upgrade FIXES (motivation)
+
+1. **XEP-0356 privileged entity (bridge roster/bookmarks).** `mod_privilege` is
+   **built into 0.12** (modulemanager has `module:send_iq()`). On 0.11 the
+   community `mod_privilege.lua` from prosody-modules is **written for 0.12 API**
+   and crashes on 0.11 (`attempt to call method 'send_iq' (a nil value)`), which
+   breaks privileged IQ → slidge cannot write bookmarks → falls back to sending
+   a gateway invite for EVERY group → client shows "миллион запросов на
+   подключение к чату" (see `slidge-flood-invites-and-roster.md`).
+2. **UnifiedPush.** `mod_unified_push` needs `util.jwt`, which only exists in
+   0.12+. On 0.11 it fails to load (`module 'util.jwt' not found`). 0.12 opens
+   the UnifiedPush route (or stay on XEP-0357 `mod_push` which works on 0.11).
+3. Bookmarks/OMEMO/PEP handling improvements.
+
+## Data compatibility & migration
+
+- Prosody's internal storage (data dir) is compatible 0.11 → 0.12; users,
+  rosters, MUC config survive. No data migration tool needed for this hop.
+- Config format is the same Lua; 0.12 adds options but accepts 0.11 configs
+  (validate with `prosodyctl check config` after the switch).
+- `component_secret` per-Component stanza (0.11 behaviour) still works.
+
+## Upgrade procedure (when approved)
+
+1. Build custom image `prosody-012` FROM `prosody/prosody:0.11.9` (keeps Lua,
+   dirs, entrypoint) + download `prosody-0.12.6.tar.gz`, `./configure
+   --prefix=/usr --sysconfdir=/etc/prosody --datadir=/var/lib/prosody`,
+   `make && make install`.
+2. Remove the community `mod_privilege.lua` from `./modules` (built-in in 0.12)
+   — but keep `privileged_entities` config, it is used the same way.
+3. `prosodyctl check config` → restart → grep logs for `Error initializing`.
+4. Verify slidge: bookmarks now written via XEP-0356 (no more invite flood),
+   `docker logs icq-slidgram` shows no `PermissionError`/privilege errors.
+5. Optional: add `mod_unified_push` (apt prosody-modules now fine) for
+   UnifiedPush, or keep XEP-0357 `mod_push`.
+6. Rollback: pin image back to `prosody/prosody:0.11.9` (data dir untouched).
+
+## Related
+
+- `xep-capability-matrix-prosody-011.md` — the XEP-0356 row there is 0.11-specific;
+  on 0.12 use the built-in module instead of the community one.
+- `push-notifications.md` — the util.jwt/0.12 dependency chain for UnifiedPush.