fix mosquitto healthcheck

Author: romkey

apps/mosquitto/.env.example

@@ -1,2 +1,7 @@
 BACKUP_DATABASE_URLS=sqlite:///opt/lib/mosquitto/mosquitto.db
 TZ=America/Los_Angeles
+
+# Docker HEALTHCHECK: authenticated subscribe to $SYS/broker/uptime (required when allow_anonymous is false).
+# Create this user with apps/mosquitto/bin/mkuser.sh (or mosquitto_passwd). If you use acl_file, allow read to $SYS/# for this user.
+MOSQUITTO_HEALTHCHECK_USERNAME=
+MOSQUITTO_HEALTHCHECK_PASSWORD=

apps/mosquitto/README.md

@@ -2,11 +2,22 @@
 
 Mosquitto provides MQTT service.
 
-Configuration file lives in `docker/mosquitto/config/mosquitto.conf`
+Configuration file lives in `apps/mosquitto/config/mosquitto.conf` (copy from `mosquitto.conf.example`).
 
-Password file lives in `lib/mosquitto/mos_passwd`
+Password file lives in `apps/mosquitto/config/mos_passwd` (see `.gitignore`; create with `bin/mkuser.sh`).
 
-You may use `docker/mosquitto/bin/mkuser.sh` to add a new user with a strong password to the broker, or run
+## Healthcheck (authenticated brokers)
+
+The container healthcheck runs `mosquitto_sub` to `$SYS/broker/uptime`. When **`allow_anonymous false`** (or you use a `password_file` without anonymous access), set in **`.env`**:
+
+- `MOSQUITTO_HEALTHCHECK_USERNAME`
+- `MOSQUITTO_HEALTHCHECK_PASSWORD`
+
+Use a dedicated low-privilege MQTT user that exists in `mos_passwd`. If you use **`acl_file`**, that user must be allowed to **subscribe/read** topics under **`$SYS/#`** (or at least `$SYS/broker/uptime`).
+
+Avoid shell metacharacters in the healthcheck password if possible (`$`, `` ` ``, `"`, `\`).
+
+You may use `apps/mosquitto/bin/mkuser.sh` to add a new user with a strong password to the broker, or run
 ```
 docker compose exec mosquitto mosquitto_passwd
 ```

apps/mosquitto/docker-compose.yml

@@ -13,11 +13,12 @@ services:
       - 1883:1883
     env_file:
       - .env
+    # Auth broker: use MOSQUITTO_HEALTHCHECK_* from .env (must match mos_passwd; needs $SYS read in ACLs if you use acl_file).
     healthcheck:
       test:
         [
           "CMD-SHELL",
-          "mosquitto_sub -h localhost -p 1883 -t '$$SYS/broker/uptime' -C 1 -W 3 || exit 1",
+          'mosquitto_sub -h localhost -p 1883 -u "$$MOSQUITTO_HEALTHCHECK_USERNAME" -P "$$MOSQUITTO_HEALTHCHECK_PASSWORD" -t "$$SYS/broker/uptime" -C 1 -W 5 || exit 1',
         ]
       interval: 30s
       timeout: 10s

docs/apps-compose-healthchecks.md

@@ -11,7 +11,7 @@ This document complements the healthchecks defined under `apps/*/docker-compose.
 | App | Check type | Notes |
 |-----|------------|--------|
 | **postgresql** | `pg_isready` | Cluster accepting connections. |
-| **mosquitto** | `mosquitto_sub` on `$SYS/broker/uptime` | **Fails if anonymous subscribers are disabled**; adjust or disable healthcheck if you require auth for all clients. |
+| **mosquitto** | `mosquitto_sub` on `$SYS/broker/uptime` with **`MOSQUITTO_HEALTHCHECK_USERNAME` / `MOSQUITTO_HEALTHCHECK_PASSWORD`** from `.env` | Required when anonymous access is disabled; user must exist in `mos_passwd` and (if using ACLs) be allowed `$SYS/#`. |
 | **vaultwarden** | HTTP `/alive` | |
 | **home-assistant** | HTTP `:8123` | Long `start_period` for first boot. |
 | **jellyfin** | HTTP `:8096/health` | |