{"id":13639953,"url":"https://github.com/donBarbos/telegram-bot-template","last_synced_at":"2025-04-20T02:32:13.589Z","repository":{"id":41140083,"uuid":"419589898","full_name":"donBarbos/telegram-bot-template","owner":"donBarbos","description":"🤖 Template for telegram bot using postgres, pgbouncer, redis, docker, amplitude, prometheus, grafana, CI with admin panel","archived":false,"fork":false,"pushed_at":"2025-04-07T15:41:14.000Z","size":4532,"stargazers_count":339,"open_issues_count":3,"forks_count":60,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-10T12:23:26.454Z","etag":null,"topics":["aiogram","aiogram-bot-template","analytics","docker","docker-compose","metrics","poetry","postgresql","pydantic","python","redis","ruff","sqlalchemy","telegram","telegram-bot","telegram-bot-example","telegram-bot-template","telegrambot","template","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donBarbos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-10-21T05:13:19.000Z","updated_at":"2025-04-07T15:41:18.000Z","dependencies_parsed_at":"2024-04-15T03:49:11.988Z","dependency_job_id":null,"html_url":"https://github.com/donBarbos/telegram-bot-template","commit_stats":null,"previous_names":[],"tags_count":16,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donBarbos%2Ftelegram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donBarbos%2Ftelegram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donBarbos%2Ftelegram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donBarbos%2Ftelegram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donBarbos","download_url":"https://codeload.github.com/donBarbos/telegram-bot-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249267813,"owners_count":21240866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","aiogram-bot-template","analytics","docker","docker-compose","metrics","poetry","postgresql","pydantic","python","redis","ruff","sqlalchemy","telegram","telegram-bot","telegram-bot-example","telegram-bot-template","telegrambot","template","uv"],"created_at":"2024-08-02T01:01:06.450Z","updated_at":"2025-04-20T02:32:13.574Z","avatar_url":"https://github.com/donBarbos.png","language":"Python","funding_links":[],"categories":["Templates"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003cem\u003eTelegram bot template\u003c/em\u003e\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003e\n  Best way to create a scalable telegram bot with analytics\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/donBarbos/telegram-bot-template/tags\"\u003e\u003cimg alt=\"GitHub tag (latest SemVer)\" src=\"https://img.shields.io/github/v/tag/donBarbos/telegram-bot-template\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/donBarbos/telegram-bot-template/actions/workflows/linters.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/donBarbos/telegram-bot-template/linters.yml?label=linters\" alt=\"Linters Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/donBarbos/telegram-bot-template/actions/workflows/docker-image.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/donBarbos/telegram-bot-template/docker-image.yml?label=docker%20image\" alt=\"Docker Build Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/donBarbos/telegram-bot-template/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/donbarbos/telegram-bot-template?color=blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Code style\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/uv\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json\" alt=\"Package manager\"\u003e\u003c/a\u003e\n\u003cp\u003e\n\n## ✨ Features\n\n-   [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/) = ❤️ )\n-   [x] Product Analytics System: using [`Amplitude`](https://amplitude.com/) or [`Posthog`](https://posthog.com/) or [`Google Analytics`](https://analytics.google.com)\n-   [x] Performance Monitoring System: using [`Prometheus`](https://prometheus.io/) and [`Grafana`](https://grafana.com/)\n-   [x] Tracking System: using [`Sentry`](https://sentry.io/)\n-   [x] Seamless use of `Docker` and `Docker Compose`\n-   [x] Export all users in `.csv` (or `.xlsx`, `.json`, `yaml` from admin panel)\n-   [x] Configured CI pipeline from git hooks to github actions\n-   [x] [`SQLAlchemy V2`](https://pypi.org/project/SQLAlchemy/) is used to communicate with the database\n-   [x] Database Migrations with [`Alembic`](https://pypi.org/project/alembic/)\n-   [x] Ability to cache using decorator\n-   [x] Convenient validation using [`Pydantic V2`](https://pypi.org/project/pydantic/)\n-   [x] Internationalization (i18n) using GNU gettex and [`Babel`](https://pypi.org/project/Babel/)\n\n## 🚀 How to Use\n\n### 🐳 Running in Docker _(recommended method)_\n\n-   configure environment variables in `.env` file\n\n-   start services\n\n    ```bash\n    docker compose up -d --build\n    ```\n\n### 💻 Running on Local Machine\n\n-   set environment and install dependencies using [uv](https://docs.astral.sh/uv/ \"python package manager\") (you can find branch with Poetry [here](https://github.com/donBarbos/telegram-bot-template/tree/poetry-archive))\n\n    ```bash\n    uv sync --frozen --all-groups\n    ```\n\n-   start the necessary services (at least your database and redis)\n\n-   configure environment variables in `.env` file\n\n-   start telegram bot\n\n    ```bash\n    uv run python -m bot\n    ```\n\n-   start admin panel\n\n    ```bash\n    uv run gunicorn -c admin/gunicorn_conf.py\n    ```\n\n-   make migrations\n\n    ```bash\n    uv run alembic upgrade head\n    ```\n\n## 🌍 Environment variables\n\nto launch the bot you only need a token bot, database and redis settings, everything else can be left out\n\n| name                     | description                                                                                 |\n| ------------------------ | ------------------------------------------------------------------------------------------- |\n| `BOT_TOKEN`              | Telegram bot API token                                                                      |\n| `RATE_LIMIT`             | Maximum number of requests allowed per minute for rate limiting                             |\n| `DEBUG`                  | Enable or disable debugging mode (e.g., `True` or `False`)                                  |\n| `USE_WEBHOOK`            | Flag to indicate whether the bot should use a webhook for updates (e.g., `True` or `False`) |\n| `WEBHOOK_BASE_URL`       | Base URL for the webhook                                                                    |\n| `WEBHOOK_PATH`           | Path to receive updates from Telegram                                                       |\n| `WEBHOOK_SECRET`         | Secret key for securing the webhook communication                                           |\n| `WEBHOOK_HOST`           | Hostname or IP address for the main application                                             |\n| `WEBHOOK_PORT`           | Port number for the main application                                                        |\n| `ADMIN_HOST`             | Hostname or IP address for the admin panel                                                  |\n| `ADMIN_PORT`             | Port number for the admin panel                                                             |\n| `DEFAULT_ADMIN_EMAIL`    | Default email for the admin user                                                            |\n| `DEFAULT_ADMIN_PASSWORD` | Default password for the admin user                                                         |\n| `SECURITY_PASSWORD_HASH` | Hashing algorithm for user passwords (e.g., `bcrypt`)                                       |\n| `SECURITY_PASSWORD_SALT` | Salt value for user password hashing                                                        |\n| `DB_HOST`                | Hostname or IP address of the PostgreSQL database                                           |\n| `DB_PORT`                | Port number for the PostgreSQL database                                                     |\n| `DB_USER`                | Username for authenticating with the PostgreSQL database                                    |\n| `DB_PASS`                | Password for authenticating with the PostgreSQL database                                    |\n| `DB_NAME`                | Name of the PostgreSQL database                                                             |\n| `REDIS_HOST`             | Hostname or IP address of the Redis database                                                |\n| `REDIS_PORT`             | Port number for the Redis database                                                          |\n| `REDIS_PASS`             | Password for authenticating with the Redis database                                         |\n| `SENTRY_DSN`             | Sentry DSN (Data Source Name) for error tracking                                            |\n| `AMPLITUDE_API_KEY`      | API key for Amplitude analytics                                                             |\n| `POSTHOG_API_KEY`        | API key for PostHog analytics                                                               |\n| `PROMETHEUS_PORT`        | Port number for the Prometheus monitoring system                                            |\n| `GRAFANA_PORT`           | Port number for the Grafana monitoring and visualization platform                           |\n| `GRAFANA_ADMIN_USER`     | Admin username for accessing Grafana                                                        |\n| `GRAFANA_ADMIN_PASSWORD` | Admin password for accessing Grafana                                                        |\n\n## 📂 Project Folder Structure\n\n```bash\n.\n├── admin # Source code for admin panel\n│   ├── __init__.py\n│   ├── app.py # Main application module for the admin panel\n│   ├── config.py # Configuration module for the admin panel\n│   ├── Dockerfile # Dockerfile for admin panel\n│   ├── gunicorn_conf.py # Gunicorn configuration file for serving admin panel\n│   ├── static # Folder for static assets\n│   │   ├── css/\n│   │   ├── fonts/\n│   │   ├── img/\n│   │   ├── js/\n│   │   └── plugins/\n│   ├── templates # HTML templates for the admin panel\n│   │   ├── admin/\n│   │   ├── index.html\n│   │   ├── my_master.html\n│   │   └── security/\n│   └── views # Custom View modules for handling web requests\n│       ├── __init__.py\n│       └── users.py\n│\n├── bot # Source code for Telegram Bot\n│   ├── __init__.py\n│   ├── __main__.py # Main entry point to launch the bot\n│   ├── analytics/ # Interaction with analytics services (e.g., Amplitude or Google Analytics)\n│   ├── cache/ # Logic for using Redis cache\n│   ├── core/ # Settings for application and other core components\n│   ├── database/ # Database functions and SQLAlchemy Models\n│   ├── filters/ # Filters for processing incoming messages or updates\n│   ├── handlers/ # Handlers for processing user commands and interactions\n│   ├── keyboards # Modules for creating custom keyboards\n│   │   ├── default_commands.py # Default command keyboards\n│   │   ├── __init__.py\n│   │   ├── inline/ # Inline keyboards\n│   │   └── reply/ # Reply keyboards\n│   ├── locales/ # Localization files for supporting multiple languages\n│   ├── middlewares/ # Middleware modules for processing incoming updates\n│   ├── services/ # Business logic for application\n│   └── utils/ # Utility functions and helper modules\n│\n├── migrations # Database Migrations managed by Alembic\n│   ├── env.py # Environment setup for Alembic\n│   ├── __init__.py\n│   ├── README\n│   ├── script.py.mako # Script template for generating migrations\n│   └── versions/ # Folder containing individual migration scripts\n│\n├── configs # Config folder for Monitoring (Prometheus, Node-exporter and Grafana)\n│   ├── grafana # Configuration files for Grafana\n│   │   └── datasource.yml\n│   └── prometheus # Configuration files for Prometheus\n│       └── prometheus.yml\n│\n├── scripts/ # Sripts folder\n├── Makefile # List of commands for standard\n├── alembic.ini # Configuration file for migrations\n├── docker-compose.yml # Docker Compose configuration file for orchestrating containers\n├── Dockerfile # Dockerfile for Telegram Bot\n├── LICENSE.md # License file for the project\n├── uv.lock # Lock file for UV dependency management\n├── pyproject.toml # Configuration file for Python projects, including build tools, dependencies, and metadata\n└── README.md # Documentation\n```\n\n## 🔧 Tech Stack\n\n-   `sqlalchemy` — object-relational mapping (ORM) library that provides a set of high-level API for interacting with relational databases\n-   `asyncpg` — asynchronous PostgreSQL database client library\n-   `aiogram` — asynchronous framework for Telegram Bot API\n-   `flask-admin` — simple and extensible administrative interface framework\n-   `loguru` — third party library for logging in Python\n-   `uv` — development workflow\n-   `docker` — to automate deployment\n-   `postgres` — powerful, open source object-relational database system\n-   `pgbouncer` — connection pooler for PostgreSQL database\n-   `redis` — in-memory data structure store used as a cache and FSM\n-   `prometheus` — time series database for collecting metrics from various systems\n-   `grafana` — visualization and analysis from various sources, including Prometheus\n\n## ⭐ Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=donBarbos/telegram-bot-template\u0026type=Date)](https://star-history.com/#donBarbos/telegram-bot-template\u0026Date)\n\n## 👷 Contributing\n\nFirst 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.\n\nIf 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!\n\n1. `Fork` this repository\n2. Create a `branch`\n3. `Commit` your changes\n4. `Push` your `commits` to the `branch`\n5. Submit a `pull request`\n\n## 📝 License\n\nDistributed under the MIT license. See [`LICENSE`](./LICENSE.md) for more information.\n\n## 📢 Contact\n\n[donbarbos](https://github.com/donBarbos): donbarbos@proton.me\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdonBarbos%2Ftelegram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FdonBarbos%2Ftelegram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdonBarbos%2Ftelegram-bot-template/lists"}