File size: 12,625 Bytes
e35e6bc |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 |
<h1 align="center"><em>Telegram bot template</em></h1>
<h3 align="center">
Best way to create a scalable telegram bot with analytics
</h3>
<p align="center">
<a href="https://github.com/donBarbos/telegram-bot-template/tags"><img alt="GitHub tag (latest SemVer)" src="https://img.shields.io/github/v/tag/donBarbos/telegram-bot-template"></a>
<a href="https://github.com/donBarbos/telegram-bot-template/actions/workflows/linters.yml"><img src="https://img.shields.io/github/actions/workflow/status/donBarbos/telegram-bot-template/linters.yml?label=linters" alt="Linters Status"></a>
<a href="https://github.com/donBarbos/telegram-bot-template/actions/workflows/docker-image.yml"><img src="https://img.shields.io/github/actions/workflow/status/donBarbos/telegram-bot-template/docker-image.yml?label=docker%20image" alt="Docker Build Status"></a>
<a href="https://www.python.org/downloads"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python"></a>
<a href="https://github.com/donBarbos/telegram-bot-template/blob/main/LICENSE"><img src="https://img.shields.io/github/license/donbarbos/telegram-bot-template?color=blue" alt="License"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Code style"></a>
<p>
## ✨ 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]
|