✨ Features
- Admin Panel based on
Flask-Admin-Dashboard
(Flask-Admin
+AdminLTE
= ❤️ ) - Product Analytics System: using
Amplitude
orPosthog
orGoogle Analytics
- Performance Monitoring System: using
Prometheus
andGrafana
- Tracking System: using
Sentry
- Seamless use of
Docker
andDocker 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 - Ability to cache using decorator
- Convenient validation using
Pydantic V2
- Internationalization (i18n) using GNU gettex
🚀 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
-
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
🌍 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 ) |
APP_HOST | Hostname or IP address for the main application |
APP_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
│
├── configs # Config folder for Monitoring (Prometheus, Node-exporter and Grafana)
│ ├── grafana # Configuration files for Grafana
│ │ └── datasource.yml
│ └── prometheus # Configuration files for Prometheus
│ └── prometheus.yml
│
├── 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 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 Pythonpoetry
— 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
👷 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 changesPush
yourcommits
to thebranch
- Submit a
pull request
📝 License
Distributed under the GPL-3.0 license. See LICENSE
for more information.