README.md

Telegram Kanban #

A Trello-style Kanban board that runs as a Telegram Mini App, with one board per group chat.

How it works #

  • Multi-tenant: the bot can be added to any number of groups; each gets its own board, scoped by chat ID. Open the bot in a private chat to see a picker across every group you're in.
  • Owner approval (optional): set OWNER_ID and newly-added groups stay unusable until you approve them via inline buttons the bot DMs you. Unset it and every group is auto-approved.
  • No membership API needed for auth: users are identified by validating Telegram's signed initData; access to a specific board is checked against a local membership cache built up as people open it (see server/src/middleware/resolveChatId.ts).
  • Discussion happens in the chat, not the app: creating a task posts an anchor message into the group; the task's "Discuss in chat" button deep-links straight to that message thread. Attachments work the same way — reply to that thread with a file and it shows up on the task.
  • Tasks support multiple assignees, a checklist, start/due dates, and archiving.
  • Data is a single SQLite file. The client polls GET /api/board every ~3s instead of using websockets. The bot itself is long-polling (getUpdates), not webhook-based — no public inbound endpoint needed beyond the Mini App's own HTTPS URL.

1. Create the bot #

  1. Open a chat with @BotFather in Telegram.
  2. Send /newbot and follow the prompts (choose a name and a unique username ending in bot).
  3. BotFather replies with an API token that looks like 123456789:AAExampleTokenValue. Save it — this is your BOT_TOKEN.

2. Register the Mini App #

  1. In BotFather, send /newapp and select your bot.
  2. Fill in the app's title, description, and image when prompted.
  3. When asked for the Web App URL, enter your deployed HTTPS URL (e.g. https://kanban.yourdomain.com). Telegram requires a real TLS certificate here — a bare IP or http:// won't work.
  4. Also set this as the bot's menu button: talk to BotFather → your bot → Bot Settings → Menu Button → set it to the same URL, so it can be opened directly from any chat.

While developing locally before you have a real HTTPS deployment, you can point the Web App URL at an ngrok/Cloudflare Tunnel HTTPS URL that forwards to your local dev server, and update it later.

3. Add the bot to a group #

Just add it as a member of any group (no admin rights required). The bot picks this up automatically via long-polling and registers the group — no manual chat-ID lookup needed anymore. If OWNER_ID is set, you'll get a DM to approve/deny it before its board becomes usable.

4. Configure environment variables #

Copy .env.example to server/.env and fill in (note: it must live in server/, since that's the working directory npm run dev:server/npm run start actually run from):

BOT_TOKEN=123456789:AAExampleTokenValue
OWNER_ID=123456789        # optional — your own Telegram user ID, see "How it works" above
PORT=3000
DB_PATH=./data/dev.db

OWNER_ID isn't your bot's ID — it's your personal Telegram user ID (the account that should receive approval prompts). Get it from a bot like @userinfobot.

5. Run it locally #

npm install
npm run build          # builds server (tsc) + client (vite)
npm run dev:server      # starts the API on PORT, serving client/dist too

For frontend-only iteration with hot reload, run the Vite dev server alongside the API (npm run dev:client, proxies /api to localhost:3000) — but note the Telegram SDK and initData validation only work when actually opened inside Telegram, so UI-only changes are easiest to preview with a mocked /api/board response; real auth flows need to be opened from Telegram itself (see below).

To test against real Telegram before you have a permanent deployment, expose your local server with a tunnel (e.g. cloudflared tunnel --url http://localhost:3000) and temporarily point the BotFather Web App URL at the HTTPS URL it gives you.

Only run one instance against a given BOT_TOKEN at a time. Telegram allows a single active getUpdates long-poll connection per bot token — running a local dev server and the production deployment simultaneously causes them to silently steal updates from each other.

6. Deploy with Kamal #

config/deploy.yml and .kamal/secrets are not tracked in git (they contain server-specific details like your host and domain) — create them yourself:

config/deploy.yml:

service: telegram-kanban
image: telegram-kanban

servers:
  web:
    - <your-server-ip-or-ssh-host-alias>

registry:
  server: localhost:5555   # local registry — Kamal builds on your machine, no external registry needed

builder:
  arch: amd64               # match your server's CPU arch

env:
  clear:
    PORT: "3000"
    DB_PATH: "/app/server/data/kanban.db"
  secret:
    - BOT_TOKEN
    - OWNER_ID

volumes:
  - "telegram_kanban_data:/app/server/data"

proxy:
  ssl: true
  host: kanban.yourdomain.com   # must already resolve to your server for Let's Encrypt to work
  app_port: 3000

.kamal/secrets:

BOT_TOKEN=<your bot token>
OWNER_ID=<your telegram user id>

Then:

  1. kamal setup (first time), then kamal deploy for subsequent deploys.
  2. The SQLite file lives on a named Docker volume (telegram_kanban_data) mounted at /app/server/data, so it survives redeploys. Back it up periodically, e.g.:
    kamal app exec 'sqlite3 /app/server/data/kanban.db ".backup /app/server/data/backup.db"'
    
  3. Once deployed, update the BotFather Web App URL (step 2) to point at your real domain if you were previously using a tunnel.

Project layout #

  • server/ — Express API + SQLite, serves the built client as static files too. Talks to Telegram both ways: outbound via server/src/telegram/botApi.ts (posting messages), and inbound via server/src/telegram/poller.ts (long-polling for group-membership and approval callback events).
  • client/ — React + Vite frontend using @telegram-apps/sdk-react.
  • config/deploy.yml — Kamal deploy config (untracked — see step 6).
  • Dockerfile — multi-stage build producing the single deployed image.

License #

MIT — see LICENSE.