Telegram bot template

Best way to create a scalable telegram bot with analytics

✨ Features

🚀 How to Use

🐳 Running in Docker (recommended method)

configure environment variables in .env file
start services
```
docker compose up -d --build
```

make migrations

docker compose exec bot alembic upgrade head

💻 Running on Local Machine

install dependencies using Poetry
```
poetry install
```
start the necessary services (at least the database and redis)
configure environment variables in .env file
start telegram bot
```
poetry run python -m bot
```

start admin panel

poetry run gunicorn -c admin/gunicorn_conf.py

make migrations
```
poetry 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
│
├── 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
├── poetry.lock # Lock file for Poetry 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
poetry — 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

👷 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 LGPL-3.0 license. See LICENSE for more information.

📢 Contact

donbarbos: donbarbos@proton.me

CavinMatrics/telegram-bot-template