magnet

module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT

README

magnet-bot

Telegram bot that crawls public procurement notices, matches them against user-configured keywords, and pushes notifications. Also supports converting notice URLs to PDF/PNG via Gotenberg.

docker run --name magnet-bot -d \
  -e TELEGRAM_BOT_TOKEN=<your_token> \
  -e SERVER_URL=https://example.com \
  ghcr.io/gythialy/magnet-bot:latest

See docs/DEPLOYMENT.md for the full deployment guide (Docker Compose, systemd, Gotenberg, webhook wiring and troubleshooting).

Environment Variables

Variable Required Default Description
TELEGRAM_BOT_TOKEN ✅ - Telegram bot token from @BotFather
TELEGRAM_BOT_NAME - - Bot username, used when building alarm record deep links
SERVER_URL ✅ - Host of the notice API, e.g. https://example.com (no trailing slash). Not validated at startup: leaving it empty starts fine but links cannot be built
MANAGER_ID - - Comma-separated Telegram user IDs allowed to run admin commands (/retry, /clean, /settings) and manage access, e.g. 10001,10002
ALLOWED_USER_IDS - - Optional comma-separated seed list of regular users, synced into the users table on startup only (first-time rollout)
SCHEDULE_INTERVAL - 1 How often the crawler runs, in hours
CRAWL_DAYS - 1 How many days back the crawler looks for notices
CONFIG_PATH - working dir Directory for bot.db and bot.log
LOG_LEVEL - debug zerolog level: trace, debug, info, warn, error. trace also enables the crawler's HTTP debug logging (very noisy)
WEBHOOK_SERVER_URL ✅ - Address Gotenberg calls back to (no port, no trailing slash), e.g. http://magnet-bot. Leaving it empty builds an invalid :8080/pdf/... callback
WEBHOOK_SERVER_PORT ✅ 0 Local HTTP port the unified server listens on; also the Gotenberg callback port. Must be non-zero, otherwise callbacks go to a random port
WEBHOOK_TOKEN - - Shared secret for webhook callbacks; enables auth when set
PDF_SERVER_URL ✅ - Gotenberg service URL, e.g. http://gotenberg:3000. Empty fails startup with create gotenberg client: empty hostname
PUBLIC_BASE_URL public mode empty Public HTTPS origin, e.g. https://bot.example.com (scheme included, no trailing slash). Empty = legacy polling mode: no webhook registration and no public entry point
TELEGRAM_WEBHOOK_SECRET with webhook - 1–256 characters of [A-Za-z0-9_-]; Telegram echoes it in X-Telegram-Bot-Api-Secret-Token
TELEGRAM_WEBHOOK_ENABLED - true Set false to keep polling even when PUBLIC_BASE_URL is set
MINI_APP_ENABLED - true Set false to keep the legacy text commands instead of serving /app/ and /api/

TELEGRAM_WEBHOOK_ENABLED and MINI_APP_ENABLED accept 1/true/on and 0/false/off; an unrecognised value falls back to their default (true).

All credential-like values (TELEGRAM_BOT_TOKEN, WEBHOOK_TOKEN, etc.) should be provided via environment variables or secrets management at deploy time. Never commit real values to the repository.

Leaving PUBLIC_BASE_URL empty keeps the legacy polling mode: no webhook is registered and nothing has to be public — WEBHOOK_SERVER_PORT still serves /healthz and the internal Gotenberg callback. The webhook ingress setup (Caddy, cloudflared, Cloudflare caveats and rollback) is documented in docs/DEPLOYMENT.md §8.

Access control — off vs restricted, the administrator list and the Mini App's Settings tab — is documented in docs/DEPLOYMENT.md §9. A database with no administrator starts in off mode; MANAGER_ID / ALLOWED_USER_IDS are startup seeds only, and day-to-day changes belong in the Settings tab.

Directories

Path Synopsis
cmd
gen command
server command
pkg
dal
server
Package server owns the single plaintext HTTP listener that fronts the bot: the Telegram webhook, the Mini App (static assets + JSON API) and the internal Gotenberg callback.
Package server owns the single plaintext HTTP listener that fronts the bot: the Telegram webhook, the Mini App (static assets + JSON API) and the internal Gotenberg callback.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL