Skip to content
/ telegram-bot-template Public template
forked from donBarbos/telegram-bot-template

🤖 Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI

License

LGPL-3.0 license
0 stars 54 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

maxktz/telegram-bot-template

BranchesTags
 
 

Repository files navigation

Telegram bot template

Best way to create a scalable telegram bot with analytics

GitHub tag (latest SemVer) Linters Status Docker Build Status Python License Code style

✨ 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!

  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 for more information.

📢 Contact

donbarbos: [email protected]

About

🤖 Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI

Resources

Readme

License

LGPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Python 67.4%
  • HTML 24.5%
  • JavaScript 5.5%
  • Dockerfile 1.2%
  • Other 1.4%