Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/donbarbos/telegram-bot-template
🤖 Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI
https://github.com/donbarbos/telegram-bot-template
aiogram aiogram-bot-template analytics database docker docker-compose metrics poetry postgresql pydantic python redis ruff sqlalchemy telegram telegram-bot telegram-bot-example telegram-bot-template telegrambot template
Last synced: 2 months ago
JSON representation
🤖 Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI
- Host: GitHub
- URL: https://github.com/donbarbos/telegram-bot-template
- Owner: donBarbos
- License: lgpl-3.0
- Created: 2021-10-21T05:13:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T02:27:56.000Z (9 months ago)
- Last Synced: 2024-04-12T10:23:53.601Z (9 months ago)
- Topics: aiogram, aiogram-bot-template, analytics, database, docker, docker-compose, metrics, poetry, postgresql, pydantic, python, redis, ruff, sqlalchemy, telegram, telegram-bot, telegram-bot-example, telegram-bot-template, telegrambot, template
- Language: Python
- Homepage:
- Size: 3.95 MB
- Stars: 134
- Watchers: 5
- Forks: 29
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Telegram bot template
Best way to create a scalable telegram bot with analytics
## ✨ Features
- [x] Admin Panel based on [`Flask-Admin-Dashboard`](https://github.com/jonalxh/Flask-Admin-Dashboard/) ([`Flask-Admin`](https://flask-admin.readthedocs.io/) + [`AdminLTE`](https://adminlte.io/) = ❤️ )
- [x] Product Analytics System: using [`Amplitude`](https://amplitude.com/) or [`Posthog`](https://posthog.com/) or [`Google Analytics`](https://analytics.google.com)
- [x] Performance Monitoring System: using [`Prometheus`](https://prometheus.io/) and [`Grafana`](https://grafana.com/)
- [x] Tracking System: using [`Sentry`](https://sentry.io/)
- [x] Seamless use of `Docker` and `Docker Compose`
- [x] Export all users in `.csv` (or `.xlsx`, `.json`, `yaml` from admin panel)
- [x] Configured CI pipeline from git hooks to github actions
- [x] [`SQLAlchemy V2`](https://pypi.org/project/SQLAlchemy/) is used to communicate with the database
- [x] Database Migrations with [`Alembic`](https://pypi.org/project/alembic/)
- [x] Ability to cache using decorator
- [x] Convenient validation using [`Pydantic V2`](https://pypi.org/project/pydantic/)
- [x] Internationalization (i18n) using GNU gettex and [`Babel`](https://pypi.org/project/Babel/)
## 🚀 How to Use
### 🐳 Running in Docker _(recommended method)_
- configure environment variables in `.env` file
- start services
```bash
docker compose up -d --build
```
### 💻 Running on Local Machine
- install dependencies using [Poetry](https://python-poetry.org "python package manager")
```bash
poetry install
```
- start the necessary services (at least the database and redis)
- configure environment variables in `.env` file
- start telegram bot
```bash
poetry run python -m bot
```
- start admin panel
```bash
poetry run gunicorn -c admin/gunicorn_conf.py
```
- make migrations
```bash
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
```bash
.
├── 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
├── 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
## ⭐ Star History
[](https://star-history.com/#donBarbos/telegram-bot-template&Date)
## 👷 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!
1. `Fork` this repository
2. Create a `branch`
3. `Commit` your changes
4. `Push` your `commits` to the `branch`
5. Submit a `pull request`
## 📝 License
Distributed under the LGPL-3.0 license. See [`LICENSE`](./LICENSE.md) for more information.
## 📢 Contact
[donbarbos](https://github.com/donBarbos): [email protected]