GitHub - SychO3/telegram-bot-template: 🤖 使用 postgres、pgbouncer、redis、docker、amplitude、prometheus、grafana 和 CI 的 telegram 机器人模板

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 Amplitude or Posthog or Google Analytics
Performance Monitoring System: using Prometheus and Grafana
Tracking System: using Sentry
Seamless use of Docker and Docker Compose
Export all users in .csv (or .xlsx, .json, yaml from admin panel)
Configured CI pipeline from git hooks to github actions
SQLAlchemy V2 is 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 .env file
start 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-groups
```
start the necessary services (at least your database and redis)
configure environment variables in .env file
start telegram bot

start admin panel

uv run gunicorn -c admin/gunicorn_conf.py

make 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 databases
asyncpg — asynchronous PostgreSQL database client library
aiogram — asynchronous framework for Telegram Bot API
flask-admin — simple and extensible administrative interface framework
loguru — third party library for logging in Python
uv — development workflow
docker — to automate deployment
postgres — powerful, open source object-relational database system
pgbouncer — connection pooler for PostgreSQL database
redis — in-memory data structure store used as a cache and FSM
prometheus — time series database for collecting metrics from various systems
grafana — 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!

Fork this repository
Create a branch
Commit your changes
Push your commits to the branch
Submit a pull request

📝 License

Distributed under the MIT license. See LICENSE for more information.

📢 Contact

donbarbos: donbarbos@proton.me