# 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)

```bash
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

```bash
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:

```bash
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):
```bash
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:
```bash
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.