donbarbos/telegram-bot-template
donbarbos/telegram-bot-template has 479 GitHub stars and 82 forks. GitHot measured -1 stars in 24 hours and -1 in 7 days. Last checked 2026-11-20 21:47 UTC. Last push 2026-08-27.
ใงใใใใจ
- Admin Panel based on Flask-Admin-Dashboard (Flask-Admin + AdminLTE = โค๏ธ )
- Product Analytics System: using Amplitude or Posthog or Google Analytics
- Performance Monitoring System: using Prometheus and Grafana
- Tracking System: using Sentry
่จๆธฌใใในใฟใผๅขๅ
- 24ๆ้
- -1
- 7ๆฅ้
- -1
- 15ๆฅ้
- ๅฑฅๆญดใๅ้ไธญ
- 1ใๆ
- ๅฑฅๆญดใๅ้ไธญ
ๆ้ใใจใฎ็ดๅขๆฐใงใใๆ้ใฏ้่คใใฆใใใๆฅๅฅใฎๅคใงใฏใใใพใใใๆช่จๆธฌใฎๅคใฏ็ฉบๆฌใงใใในใฟใผๆฐใฏๆณจ็ฎๅบฆใฎๆๆจใงใใใๅ่ณชใฎไฟ่จผใงใฏใใใพใใใ
ๆฆ่ฆ
๐ค Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI with admin panel
ใใผใฟREADME.md
ใชใชใธใใซTelegram bot template
Best way to create a scalable telegram bot with analytics
โจ Features
- Admin Panel based on
Flask-Admin-Dashboard(Flask-Admin+AdminLTE= โค๏ธ ) - Product Analytics System: using
AmplitudeorPosthogorGoogle Analytics - Performance Monitoring System: using
PrometheusandGrafana - Tracking System: using
Sentry - Seamless use of
DockerandDocker Compose - Export all users in
.csv(or.xlsx,.json,yamlfrom admin panel) - Configured CI pipeline from git hooks to github actions
-
SQLAlchemy V2is used to communicate with the database - Database Migrations with
Alembic - Ability to cache using decorator
- Convenient validation using
Pydantic V2 - Internationalization (i18n) using GNU gettex and
Babel
๐ How to Use
๐ณ Running in Docker (recommended method)
configure environment variables in
.envfilestart services
docker compose up -d --build
๐ป Running on Local Machine
set environment and install dependencies using uv (you can find branch with Poetry here)
uv sync --frozen --all-groupsstart the necessary services (at least your database and redis)
configure environment variables in
.envfilestart telegram bot
uv run python -m botstart admin panel
uv run gunicorn -c admin/gunicorn_conf.pymake migrations
uv run alembic upgrade head
๐ Environment variables
to launch the bot you only need a token bot, database and redis settings, everything else can be left out
| name | description |
|---|---|
BOT_TOKEN |
Telegram bot API token |
RATE_LIMIT |
Maximum number of requests allowed per minute for rate limiting |
DEBUG |
Enable or disable debugging mode (e.g., True or False) |
USE_WEBHOOK |
Flag to indicate whether the bot should use a webhook for updates (e.g., True or False) |
WEBHOOK_BASE_URL |
Base URL for the webhook |
WEBHOOK_PATH |
Path to receive updates from Telegram |
WEBHOOK_SECRET |
Secret key for securing the webhook communication |
WEBHOOK_HOST |
Hostname or IP address for the main application |
WEBHOOK_PORT |
Port number for the main application |
ADMIN_HOST |
Hostname or IP address for the admin panel |
ADMIN_PORT |
Port number for the admin panel |
DEFAULT_ADMIN_EMAIL |
Default email for the admin user |
DEFAULT_ADMIN_PASSWORD |
Default password for the admin user |
SECURITY_PASSWORD_HASH |
Hashing algorithm for user passwords (e.g., bcrypt) |
SECURITY_PASSWORD_SALT |
Salt value for user password hashing |
DB_HOST |
Hostname or IP address of the PostgreSQL database |
DB_PORT |
Port number for the PostgreSQL database |
DB_USER |
Username for authenticating with the PostgreSQL database |
DB_PASS |
Password for authenticating with the PostgreSQL database |
DB_NAME |
Name of the PostgreSQL database |
REDIS_HOST |
Hostname or IP address of the Redis database |
REDIS_PORT |
Port number for the Redis database |
REDIS_PASS |
Password for authenticating with the Redis database |
SENTRY_DSN |
Sentry DSN (Data Source Name) for error tracking |
AMPLITUDE_API_KEY |
API key for Amplitude analytics |
POSTHOG_API_KEY |
API key for PostHog analytics |
PROMETHEUS_PORT |
Port number for the Prometheus monitoring system |
GRAFANA_PORT |
Port number for the Grafana monitoring and visualization platform |
GRAFANA_ADMIN_USER |
Admin username for accessing Grafana |
GRAFANA_ADMIN_PASSWORD |
Admin password for accessing Grafana |
๐ Project Folder Structure
.
โโโ admin # Source code for admin panel
โ โโโ __init__.py
โ โโโ app.py # Main application module for the admin panel
โ โโโ config.py # Configuration module for the admin panel
โ โโโ Dockerfile # Dockerfile for admin panel
โ โโโ gunicorn_conf.py # Gunicorn configuration file for serving admin panel
โ โโโ static # Folder for static assets
โ โ โโโ css/
โ โ โโโ fonts/
โ โ โโโ img/
โ โ โโโ js/
โ โ โโโ plugins/
โ โโโ templates # HTML templates for the admin panel
โ โ โโโ admin/
โ โ โโโ index.html
โ โ โโโ my_master.html
โ โ โโโ security/
โ โโโ views # Custom View modules for handling web requests
โ โโโ __init__.py
โ โโโ users.py
โ
โโโ bot # Source code for Telegram Bot
โ โโโ __init__.py
โ โโโ __main__.py # Main entry point to launch the bot
โ โโโ analytics/ # Interaction with analytics services (e.g., Amplitude or Google Analytics)
โ โโโ cache/ # Logic for using Redis cache
โ โโโ core/ # Settings for application and other core components
โ โโโ database/ # Database functions and SQLAlchemy Models
โ โโโ filters/ # Filters for processing incoming messages or updates
โ โโโ handlers/ # Handlers for processing user commands and interactions
โ โโโ keyboards # Modules for creating custom keyboards
โ โ โโโ default_commands.py # Default command keyboards
โ โ โโโ __init__.py
โ โ โโโ inline/ # Inline keyboards
โ โ โโโ reply/ # Reply keyboards
โ โโโ locales/ # Localization files for supporting multiple languages
โ โโโ middlewares/ # Middleware modules for processing incoming updates
โ โโโ services/ # Business logic for application
โ โโโ utils/ # Utility functions and helper modules
โ
โโโ migrations # Database Migrations managed by Alembic
โ โโโ env.py # Environment setup for Alembic
โ โโโ __init__.py
โ โโโ README
โ โโโ script.py.mako # Script template for generating migrations
โ โโโ versions/ # Folder containing individual migration scripts
โ
โโโ configs # Config folder for Monitoring (Prometheus, Node-exporter and Grafana)
โ โโโ grafana # Configuration files for Grafana
โ โ โโโ datasource.yml
โ โโโ prometheus # Configuration files for Prometheus
โ โโโ prometheus.yml
โ
โโโ scripts/ # Sripts folder
โโโ Makefile # List of commands for standard
โโโ alembic.ini # Configuration file for migrations
โโโ docker-compose.yml # Docker Compose configuration file for orchestrating containers
โโโ Dockerfile # Dockerfile for Telegram Bot
โโโ LICENSE.md # License file for the project
โโโ uv.lock # Lock file for UV dependency management
โโโ pyproject.toml # Configuration file for Python projects, including build tools, dependencies, and metadata
โโโ README.md # Documentation
๐ง Tech Stack
sqlalchemyโ object-relational mapping (ORM) library that provides a set of high-level API for interacting with relational databasesasyncpgโ asynchronous PostgreSQL database client libraryaiogramโ asynchronous framework for Telegram Bot APIflask-adminโ simple and extensible administrative interface frameworkloguruโ third party library for logging in Pythonuvโ development workflowdockerโ to automate deploymentpostgresโ powerful, open source object-relational database systempgbouncerโ connection pooler for PostgreSQL databaseredisโ in-memory data structure store used as a cache and FSMprometheusโ time series database for collecting metrics from various systemsgrafanaโ visualization and analysis from various sources, including Prometheus
โญ Star History
๐ท Contributing
First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
Forkthis repository- Create a
branch Commityour changesPushyourcommitsto thebranch- Submit a
pull request
๐ License
Distributed under the MIT license. See LICENSE for more information.