Module loading & restart verification (2026-08-29)

How to safely add community/custom modules to Prosody 0.11 (Docker) and verify a restart actually worked, without misreading stale logs.

Add a community module (from Ubuntu prosody-modules apt)

sudo apt-get install -y prosody-modules            # → /usr/lib/prosody/modules/
# copy ONLY the wanted module into the project's ./modules (mounted as /etc/prosody/modules)
cp -r /usr/lib/prosody/modules/mod_vcard_muc      /opt/icq/modules/
# mod_admin_web is stdlib NOT in prosody-modules → clone repo yurt-page/xmpp_admin_web

Restart sequence — do this in order

docker exec icq-prosody prosodyctl check config    # 1. syntax gate → "All checks passed"
docker compose restart prosody                     # 2. restart
# 3. verify — see "What to check" below

CRITICAL: `docker logs` may be EMPTY — check the file logs

The prosody.cfg.lua log block writes to /var/log/prosody/prosody.{log,err} which is bind-mounted to ./logs/. So docker logs icq-prosody often shows nothing for normal startup. Read the real logs:

tail -50 /opt/icq/logs/prosody.log                 # runtime info (ports, modules, auth)
tail -50 /opt/icq/logs/prosody.err                 # errors / module stack traces

What to check after a restart (confirmed-working evidence)

Scan the file log for the post-boot lines (Activated service, Certificates loaded):

portmanager info Activated service 'c2s' on [0.0.0.0]:5222
s2s on 5269, http on 5280, https on 5281
per-domain Certificates loaded (nixg.ru, conference., upload.)
HTTP Upload module prints URL: <https://.../upload> + Storage path
clients authenticate (Authenticated as admin@nixg.ru), s2s federation streams open

Quick HTTP probes (no auth needed):

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:5280/http-bind   # BOSH → 200
curl -sk -o /dev/null -w '%{http_code}\n' --resolve upload.nixg.ru:5281:127.0.0.1 https://upload.nixg.ru:5281/  # 404 on root is OK

Pitfall: stale errors in prosody.err will mislead you

/opt/icq/logs/prosody.err is append-only and can hold OLD errors from earlier boots (e.g. http_upload MUST happen with TLS from BEFORE the LE cert was wired, or Failed to open server port 5222 from a double-start). When investigating a restart, only trust entries dated AFTER your restart timestamp:

awk '/Aug 29 08:07/,0' /opt/icq/logs/prosody.err | tail -30

No entries after the restart timestamp ⇒ the boot was clean.

FACTS about specific modules (verified by restart 2026-08-29)

mod_admin_web is NOT a web admin panel. Despite the name, the yurt-page/xmpp_admin_web mod_admin_web.lua is an XMPP ad-hoc admin module (adminsub, per-session admin commands). It serves no HTTP page: GET /admin on :5280 → 404. Prosody 0.11 has no built-in web admin UI (people bolt on separate UI projects). Do not promise a "/admin web panel".
mod_bosh produces a harmless mod_bosh warn Unable to associate request with a session when you curl the empty POST /http-bind endpoint — not a fault.
mod_vcard_muc (XEP-0153 avatars in MUC) and mod_muc_moderation load on the MUC Component, via Component ... modules = { "vcard_muc", "muc_moderation" }, not in global modules_enabled. They load cleanly under 0.11.
mod_http_upload_external is the external-storage variant of HTTP Upload; kept installed but usually left disabled when classic mod_http_upload works.

3.5 KiB Raw Permalink Blame History