https://github.com/vlymar1/aiogram-bot-template
Python aiogram Telegram bot template, scalable and modular with PostgreSQL, Redis, Docker Compose, Ruff, and built-in admin panel with user metrics.
https://github.com/vlymar1/aiogram-bot-template
aiogram alembic boilerplate bot compose docker postgresql pydantic python redis scalable sqlalchemy telegram template
Last synced: about 2 months ago
JSON representation
Python aiogram Telegram bot template, scalable and modular with PostgreSQL, Redis, Docker Compose, Ruff, and built-in admin panel with user metrics.
- Host: GitHub
- URL: https://github.com/vlymar1/aiogram-bot-template
- Owner: vlymar1
- License: mit
- Created: 2025-05-08T07:53:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-20T19:23:26.000Z (about 1 year ago)
- Last Synced: 2025-09-07T07:24:55.666Z (10 months ago)
- Topics: aiogram, alembic, boilerplate, bot, compose, docker, postgresql, pydantic, python, redis, scalable, sqlalchemy, telegram, template
- Language: Python
- Homepage:
- Size: 84 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# aiogram-bot-template 🤖
#### 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.
[](https://www.python.org/)
[](https://aiogram.dev/)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](https://www.docker.com/)
[](https://www.sqlalchemy.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
[](LICENSE)
[](https://github.com/vlymar-dev/aiogram-bot-template/actions)
## 📋 Table of Contents
- [Description](#-description)
- [Features](#-features)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Security](#-security)
- [Project Structure](#-project-structure)
- [Usage](#-usage)
- [Contributing](#-contributing)
- [License](#-license)
- [Contact](#-contact)
## 📖 Description
`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.
This template simplifies environment setup, reduces boilerplate code, and provides out-of-the-box tools for database management, caching, and logging.
## ✨ Features
- 🌐 **Modular Structure**: Easily extensible with separated handlers, services, and DAO.
- 🗄️ **Database**: PostgreSQL support with base and custom DAO methods, plus Alembic migrations.
- ⚡ **Caching**: Redis integration for storing user data (telegram_id, language_code, is_admin, is_banned).
- 🛡️ **Admin Panel**: Basic panel displaying user statistics (total, new today/weekly/monthly).
- 🚫 **Filters**: Implemented `is_admin` and `is_banned` filters for access control.
- 📜 **Logging**: Structured JSON logging to console and file with rotation, configurable via .env. Details in [Logging Documentation](docs/LOGGING.md).
- ✅ **Validation**: Pydantic for configuration and data validation.
- 🛠️ **CI/CD**: Linting via GitHub Actions and automated Docker image builds on GHCR.
- 🐳 **Docker**: Full Docker and Docker Compose support with configs for Poetry and pip.
- 📈 **Scalability**: Suitable for large-scale bots thanks to services, caching, and modularity.
## 🚀 Installation
### Local Setup
1. Clone the repository:
```bash
git clone https://github.com/vlymar-dev/aiogram-bot-template.git
cd aiogram-bot-template
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
Or, if using Poetry:
```bash
poetry install
```
3. Configure the `.env` file (see [Configuration](#-configuration)).
4. Apply database migrations:
```bash
make migration-apply
```
5. Run the bot:
```bash
make run-main
```
### Using Docker
1. Clone the repository (see above).
2. Configure `.env`.
3. Start services:
```bash
make services-build
```
Or start without rebuilding:
```bash
make services-up
```
4. For local development with DB and Redis:
```bash
make local-up
```
### Useful Commands
The project includes a `Makefile` with handy commands:
- `make lint` — Run code quality checks (ruff, pre-commit).
- `make migration-create MESSAGE="description"` — Create a new migration.
- `make services-down` — Stop services.
- `make storages-clear` — Remove containers and volumes.
- `make help` — List all commands.
## 🔧 Configuration
Create a `.env` file in the project root based on `.env.example`:
```bash
cp .env.example .env
```
Edit `.env` to configure the bot, database, Redis, and logging. See the example configuration:
View 📄 [.env.example](https://github.com/vlymar-dev/aiogram-bot-template/blob/main/.env.example)
## ⚠️ Security
**Production Security Policy**:
Do not expose PostgreSQL (port 5432) or Redis (port 6379) publicly. Use an SSH tunnel or Docker's internal network for access.
## 📂 Project Structure
```
aiogram-bot-template/
├── Dockerfile # Dockerfile
├── LICENSE # MIT License
├── Makefile # Convenient commands
├── README.md # Documentation
├── alembic/ # Database migrations
├── docker_compose/ # Docker Compose configurations
├── docs/ # Additional documentation
├── src/
│ ├── bot/ # Bot logic
│ │ ├── bot.py # Entry point
│ │ ├── filters/ # Filters (admin, banned)
│ │ ├── handlers/ # Command handlers
│ │ ├── keyboards/ # Keyboards
│ │ ├── middlewares/ # Middleware for DB and services
│ │ └── utils/ # Utilities
│ ├── config.py # Pydantic-based configuration
│ ├── infrastructure/ # Infrastructure (DB, cache, services)
│ └── logging_config.py # Logging setup
├── tests/ # Tests
├── .env.example # Configuration example
├── poetry.lock # Poetry dependencies
├── pyproject.toml # Poetry config
├── requirements.txt # pip dependencies
```
## 🛠️ Usage
Once launched, the bot automatically registers users upon the `/start` command. The main menu, accessible via an inline keyboard, provides the following features:
- 🛡️ **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.
- 👤 **Profile**: Shows cached user data (telegram_id, language_code, is_admin, is_banned) when the "My Profile" button is clicked.
- 📎 **Share Bot**: Allows sharing the bot link via `switch_inline_query` by clicking the "Share Bot" button.
To access the main menu, send the `/start` command and interact with the inline keyboard.
## 🤝 Contributing
We welcome contributions! Want to add new handlers, improve documentation, or fix a bug? Here's how:
1. Fork the repository.
2. Create a branch (`git checkout -b feature/awesome-feature`).
3. Make changes and commit (`git commit -m "feat: Add awesome feature"`).
4. Push the branch (`git push origin feature/awesome-feature`).
5. Open a Pull Request.
## 📜 License
This project is licensed under the [MIT License](LICENSE).
## 📬 Contact
Reach out via [GitHub](https://github.com/vlymar-dev) or open an issue in the repository.