Docs overhaul: beginner quick start + all-in-one NocoDB stack

- README rewritten around a copy-paste quick start (CLI and Portainer), verified alert test, day-to-day NocoDB operations, troubleshooting table, FAQ - new docker-compose.allinone.yml: NocoDB (pinned 2026.09.0, SQLite) + monitor on a private network, with healthchecks and the Telegram IPv4 pin documented - docs/: QUICKSTART-PORTAINER, TELEGRAM-SETUP, NOCODB-SETUP, ARCHITECTURE, OPERATIONS, TROUBLESHOOTING (replace DOCUMENTATION.md + COMPOSE-SETUP.md) - secrets: SECRETS.md is gitignored and untracked; tracked template is SECRETS.example.md; real base id / chat id removed from .env.example - LICENSE (MIT), .gitignore/.dockerignore tidied - AGENTS.md: layout, iron rules, verification gates; host-specific deploy details moved to the gitignored OPS-INTERNAL.md
2026-10-06 16:37:59 +08:00
parent 44851a1c29
commit 5d9db48a26
16 changed files with 1354 additions and 647 deletions
@@ -0,0 +1,71 @@
+# Telegram setup
+
+Two values are needed: a **bot token** (who sends) and a **chat id** (where it sends). Both are free and take about a minute.
+
+---
+
+## 1. Create the bot
+
+1. Open Telegram and search for **@BotFather** (the one with a blue checkmark).
+2. Send `/newbot`.
+3. It asks for a **name** — anything, e.g. `My Carousell Alerts`.
+4. It asks for a **username** — must be unique and end in `bot`, e.g. `mycarousell_alerts_bot`.
+5. It replies with a token like:
+
+   ```
+   Use this token to access the HTTP API:
+   8123456789:AAF7xK3nQw8_your_token_here_9dZ
+   ```
+
+   That whole string is `TELEGRAM_BOT_TOKEN`. Treat it like a password — anyone holding it can send and read messages as your bot.
+
+Optional, but nice: `/setdescription` and `/setuserpic` to make the alert messages look intentional.
+
+## 2. Get your chat id (alert yourself)
+
+1. **Send your new bot a message** — click the link BotFather gave you and say `hi`. This step matters: until you have messaged the bot, it is not allowed to message you, and sends fail with `chat not found`.
+2. Message **@userinfobot**. It replies with your id:
+
+   ```
+   Id: 123456789
+   ```
+
+   That number is `TELEGRAM_CHAT_ID`.
+
+## 3. Or alert a group
+
+1. Create the group (or use an existing one) and **add your bot** to it as a member.
+2. Send a message in the group (any text).
+3. Read the group's chat id:
+
+   ```bash
+   curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"
+   ```
+
+   Look for `"chat":{"id":-1001234567890,"title":"..."}`. Group ids are **negative** and usually start with `-100`. Use that number as `TELEGRAM_CHAT_ID`.
+
+If `getUpdates` returns `{"ok":true,"result":[]}`, the bot has not seen any message yet — send another one in the group and retry.
+
+## 4. Verify before you blame the monitor
+
+```bash
+# who am I?
+curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
+
+# send a test message
+curl -s -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
+     -d chat_id=<YOUR_CHAT_ID> -d text="hello from carousell-monitor"
+```
+
+Expected: `{"ok":true,...}` and a message on your phone. If this works, the monitor's credentials are right and anything missing is a monitor-side issue (filters, `notify` checkbox, pending queue).
+
+| Error | Meaning |
+|---|---|
+| `401 Unauthorized` | token is wrong, or it was revoked in BotFather |
+| `400 chat not found` | wrong chat id, or you never messaged the bot / the bot is not in the group |
+| `403 bot was blocked by the user` | you blocked the bot — unblock it |
+| the `curl` hangs forever | DNS/IPv6 trouble. The compose files pin `api.telegram.org` to its IPv4 address in `extra_hosts`; refresh that IP with `dig +short api.telegram.org` |
+
+## 5. Rotate it later
+
+If the token leaks: @BotFather → `/revoke` → pick the bot → you get a new token. Update `.env` (or the Portainer stack environment) and restart the monitor.