initial

README.md

@@ -0,0 +1,62 @@
+# truenas-catalog-notify
+
+Lightweight TrueNAS Apps catalog watcher that sends Telegram alerts when the catalog changes.
+
+## What it tracks
+
+The watcher pulls `https://apps.truenas.com/catalog` over plain HTTP (no browser/emulation), parses app cards, and compares these fields against a saved snapshot:
+
+- app name
+- app URL
+- train
+- added date
+- summary text
+
+On changes, it sends Telegram messages with:
+
+- added apps (`+`)
+- removed apps (`-`)
+- updated apps (`~`) and field-level diffs
+
+## Environment variables
+
+- `TELEGRAM_BOT_TOKEN` (required for notifications)
+- `TELEGRAM_CHAT_ID` (required for notifications)
+- `CHECK_INTERVAL_SECONDS` (default: `1800`)
+- `STATE_PATH` (default: `/data/catalog_state.json`)
+- `CATALOG_URL` (default: `https://apps.truenas.com/catalog`)
+- `REQUEST_TIMEOUT_SECONDS` (default: `30`)
+- `LOG_LEVEL` (default: `INFO`)
+
+## Build
+
+```bash
+docker build -t truenas-catalog-notify .
+```
+
+## Run
+
+```bash
+docker run -d \
+  --name truenas-catalog-notify \
+  -e TELEGRAM_BOT_TOKEN=123456:ABC... \
+  -e TELEGRAM_CHAT_ID=123456789 \
+  -e CHECK_INTERVAL_SECONDS=1800 \
+  -v truenas-catalog-notify-data:/data \
+  --restart unless-stopped \
+  truenas-catalog-notify
+```
+
+## Notes
+
+- First run only stores the initial snapshot (no notification).
+- Notifications start when a later check differs from the saved snapshot.
+- If Telegram variables are missing, the watcher logs changes but skips sending messages.
+- If you hit permissions on `/data/catalog_state.json`, rebuild and recreate the container with the latest image.
+
+## Rebuild after changes
+
+```bash
+docker compose build --no-cache
+docker compose up -d --force-recreate
+```