aiogram-bot-template 🤖

A template for rapidly building scalable Telegram bots using aiogram. Designed for developers who want to streamline project setup with a modular structure, database support, caching, and a basic admin panel.

📋 Table of Contents

• Description
• Features
• Installation
• Configuration
• Security
• Project Structure
• Usage
• Contributing
• License
• 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.
• ✅ 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:

   git clone https://github.com/vlymar-dev/aiogram-bot-template.git
   cd aiogram-bot-template

2. Install dependencies:

   pip install -r requirements.txt

   Or, if using Poetry:

   poetry install

3. Configure the .env file (see Configuration).
4. Apply database migrations:

   make migration-apply

5. Run the bot:

   make run-main

Using Docker

1. Clone the repository (see above).
2. Configure .env.
3. Start services:

   make services-build

   Or start without rebuilding:

   make services-up

4. For local development with DB and Redis:

   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:

cp .env.example .env

Edit .env to configure the bot, database, Redis, and logging. See the example configuration:

View 📄 .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.

📬 Contact

Reach out via GitHub or open an issue in the repository.