{"id":30851612,"url":"https://github.com/vlymar1/aiogram-bot-template","last_synced_at":"2026-05-05T04:10:13.309Z","repository":{"id":306992484,"uuid":"979875432","full_name":"vlymar1/aiogram-bot-template","owner":"vlymar1","description":"Python aiogram Telegram bot template, scalable and modular with PostgreSQL, Redis, Docker Compose, Ruff, and built-in admin panel with user metrics.","archived":false,"fork":false,"pushed_at":"2025-06-20T19:23:26.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T07:24:55.666Z","etag":null,"topics":["aiogram","alembic","boilerplate","bot","compose","docker","postgresql","pydantic","python","redis","scalable","sqlalchemy","telegram","template"],"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/vlymar1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-08T07:53:32.000Z","updated_at":"2025-08-07T07:16:28.000Z","dependencies_parsed_at":"2026-02-02T12:03:04.716Z","dependency_job_id":null,"html_url":"https://github.com/vlymar1/aiogram-bot-template","commit_stats":null,"previous_names":["vlymar1/aiogram-bot-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vlymar1/aiogram-bot-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Faiogram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Faiogram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Faiogram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Faiogram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlymar1","download_url":"https://codeload.github.com/vlymar1/aiogram-bot-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2Faiogram-bot-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32634786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"online","status_checked_at":"2026-05-05T02:00:06.033Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","alembic","boilerplate","bot","compose","docker","postgresql","pydantic","python","redis","scalable","sqlalchemy","telegram","template"],"created_at":"2025-09-07T07:18:17.798Z","updated_at":"2026-05-05T04:10:13.303Z","avatar_url":"https://github.com/vlymar1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aiogram-bot-template 🤖\n\n#### A template for rapidly building scalable Telegram bots using [aiogram](https://aiogram.dev/). Designed for developers who want to streamline project setup with a modular structure, database support, caching, and a basic admin panel.\n\n[![Python](https://img.shields.io/badge/Python-3.12.5-blue.svg)](https://www.python.org/)\n[![aiogram](https://img.shields.io/badge/aiogram-3.20.0-green.svg)](https://aiogram.dev/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16.8-336791?style=flat\u0026logo=PostgreSQL\u0026logoColor=white)](https://www.postgresql.org/)\n[![Redis](https://img.shields.io/badge/Redis-7.4.2-DC382D?style=flat\u0026logo=Redis\u0026logoColor=white)](https://redis.io/)\n[![Docker](https://img.shields.io/badge/Docker-24.0-2496ED?style=flat\u0026logo=Docker\u0026logoColor=white)](https://www.docker.com/)\n[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-D71F00?style=flat\u0026logo=sqlalchemy\u0026logoColor=white)](https://www.sqlalchemy.org/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://img.shields.io/badge/CI-GitHub_Actions-blue.svg)](https://github.com/vlymar-dev/aiogram-bot-template/actions)\n\n\n## 📋 Table of Contents\n- [Description](#-description)\n- [Features](#-features)\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [Security](#-security)\n- [Project Structure](#-project-structure)\n- [Usage](#-usage)\n- [Contributing](#-contributing)\n- [License](#-license)\n- [Contact](#-contact)\n\n## 📖 Description\n`aiogram-bot-template` is a ready-to-use template for developing Telegram bots with Python and the aiogram library. It offers a modular architecture, automated connections to PostgreSQL and Redis, a built-in admin panel, filters, Pydantic-based validation, and CI/CD support. The template is ideal for building scalable bots, from simple prototypes to complex enterprise solutions.\n\nThis template simplifies environment setup, reduces boilerplate code, and provides out-of-the-box tools for database management, caching, and logging.\n\n## ✨ Features\n- 🌐 **Modular Structure**: Easily extensible with separated handlers, services, and DAO.\n- 🗄️ **Database**: PostgreSQL support with base and custom DAO methods, plus Alembic migrations.\n- ⚡ **Caching**: Redis integration for storing user data (telegram_id, language_code, is_admin, is_banned).\n- 🛡️ **Admin Panel**: Basic panel displaying user statistics (total, new today/weekly/monthly).\n- 🚫 **Filters**: Implemented `is_admin` and `is_banned` filters for access control.\n- 📜 **Logging**: Structured JSON logging to console and file with rotation, configurable via .env. Details in [Logging Documentation](docs/LOGGING.md).\n- ✅ **Validation**: Pydantic for configuration and data validation.\n- 🛠️ **CI/CD**: Linting via GitHub Actions and automated Docker image builds on GHCR.\n- 🐳 **Docker**: Full Docker and Docker Compose support with configs for Poetry and pip.\n- 📈 **Scalability**: Suitable for large-scale bots thanks to services, caching, and modularity.\n\n## 🚀 Installation\n\n### Local Setup\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/vlymar-dev/aiogram-bot-template.git\n   cd aiogram-bot-template\n   ```\n2. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n   Or, if using Poetry:\n   ```bash\n   poetry install\n   ```\n3. Configure the `.env` file (see [Configuration](#-configuration)).\n4. Apply database migrations:\n   ```bash\n   make migration-apply\n   ```\n5. Run the bot:\n   ```bash\n   make run-main\n   ```\n\n### Using Docker\n1. Clone the repository (see above).\n2. Configure `.env`.\n3. Start services:\n   ```bash\n   make services-build\n   ```\n   Or start without rebuilding:\n   ```bash\n   make services-up\n   ```\n4. For local development with DB and Redis:\n   ```bash\n   make local-up\n   ```\n\n### Useful Commands\nThe project includes a `Makefile` with handy commands:\n- `make lint` — Run code quality checks (ruff, pre-commit).\n- `make migration-create MESSAGE=\"description\"` — Create a new migration.\n- `make services-down` — Stop services.\n- `make storages-clear` — Remove containers and volumes.\n- `make help` — List all commands.\n\n## 🔧 Configuration\nCreate a `.env` file in the project root based on `.env.example`:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` to configure the bot, database, Redis, and logging. See the example configuration:\n\nView 📄 [.env.example](https://github.com/vlymar-dev/aiogram-bot-template/blob/main/.env.example)\n\n## ⚠️ Security\n**Production Security Policy**:\nDo not expose PostgreSQL (port 5432) or Redis (port 6379) publicly. Use an SSH tunnel or Docker's internal network for access.\n\n## 📂 Project Structure\n```\naiogram-bot-template/\n├── Dockerfile                  # Dockerfile\n├── LICENSE                     # MIT License\n├── Makefile                    # Convenient commands\n├── README.md                   # Documentation\n├── alembic/                    # Database migrations\n├── docker_compose/             # Docker Compose configurations\n├── docs/                       # Additional documentation\n├── src/\n│   ├── bot/                    # Bot logic\n│   │   ├── bot.py              # Entry point\n│   │   ├── filters/            # Filters (admin, banned)\n│   │   ├── handlers/           # Command handlers\n│   │   ├── keyboards/          # Keyboards\n│   │   ├── middlewares/        # Middleware for DB and services\n│   │   └── utils/              # Utilities\n│   ├── config.py               # Pydantic-based configuration\n│   ├── infrastructure/         # Infrastructure (DB, cache, services)\n│   └── logging_config.py       # Logging setup\n├── tests/                      # Tests\n├── .env.example                # Configuration example\n├── poetry.lock                 # Poetry dependencies\n├── pyproject.toml              # Poetry config\n├── requirements.txt            # pip dependencies\n```\n\n## 🛠️ Usage\nOnce launched, the bot automatically registers users upon the `/start` command. The main menu, accessible via an inline keyboard, provides the following features:\n\n- 🛡️ **Admin Panel**: Displays user statistics (total, new today/weekly/monthly). Accessible to users with `is_admin=True` or Telegram IDs listed in `BOT_ADMIN_ACCESS_IDs` in the `.env` file.\n- 👤 **Profile**: Shows cached user data (telegram_id, language_code, is_admin, is_banned) when the \"My Profile\" button is clicked.\n- 📎 **Share Bot**: Allows sharing the bot link via `switch_inline_query` by clicking the \"Share Bot\" button.\n\nTo access the main menu, send the `/start` command and interact with the inline keyboard.\n\n\n## 🤝 Contributing\nWe welcome contributions! Want to add new handlers, improve documentation, or fix a bug? Here's how:\n1. Fork the repository.\n2. Create a branch (`git checkout -b feature/awesome-feature`).\n3. Make changes and commit (`git commit -m \"feat: Add awesome feature\"`).\n4. Push the branch (`git push origin feature/awesome-feature`).\n5. Open a Pull Request.\n\n## 📜 License\nThis project is licensed under the [MIT License](LICENSE).\n\n## 📬 Contact\nReach out via [GitHub](https://github.com/vlymar-dev) or open an issue in the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Faiogram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlymar1%2Faiogram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Faiogram-bot-template/lists"}