xmpp-server-prosody/references/prosody-012-upgrade-path.md

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.