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.
What you can do
- 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
Gemessener Sternzuwachs
- in 24h
- -1
- in 7 days
- -1
- in 15 days
- Verlauf wird gesammelt
- in 1 month
- Verlauf wird gesammelt
NettoΓ€nderungen in ΓΌberlappenden ZeitrΓ€umen, keine Tagessummen. Fehlende Messwerte bleiben leer. Sterne zeigen Interesse, nicht QualitΓ€t.
Γber uns
π€ Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI with admin panel
DatenREADME.md
OriginalTelegram 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.