Telegram Bot Template

🚀 Quickstart

Ensure uv is installed, then create a new Telegram bot project with:

uvx --with copier-templates-extensions copier copy --trust -r HEAD gh:TimNekk/copier-telegram-bot ~/path/to/your/project

✨ Features

Built with Copier, this template lets you toggle features during setup - choose what you need and generate files instantly! Ready for Docker 🐳 and Coolify ☁️ deployment.

Core Infrastructure

• Docker Compose 🐳 Launch bot + services with one command
• Python 3.9–3.13 🐍 Choose your Python version easily
• uv 🚀 Fast dependency management powered by Rust
• Poetry 📦 Manage dependencies safely with virtual environments
• pip 📜 Classic Python package installer

Telegram Bot Framework

• Aiogram ⚡ Modern async bot framework with state management
• Aiogram Dialog 🖼️ Create menus and interactive interfaces
• Redis ❤️ Keep bot data safe between restarts

Database & ORM

• PostgreSQL 🐘 Powerful database for complex projects
• SQLAlchemy 🛠️ Work with databases using Python code
• Alembic ⏳ Track and apply database changes easily
• User Table 👤 id, username, first_name, last_name, etc

Middlewares

• Dependency Injection 💉 Share tools/data across bot handlers
• Throttling 🛑 Stop spam with automatic speed limits
• Database Sessions ♻️ Auto-manage database connections
• Loguru 📜 Simple logging with colors and fun
• User Register 📝 Adds a user to the database on /start
• Callback Answer 🔄 Automatically answer callback queries

Tooling

• PostHog 📊 Product analytics with user tracking and event capture
• i18n 🌐 Multiple languages support
• Dependabot 🤖 Automatic dependency updates
• Pydantic Settings ✅ Safe config management with type checking
• Dynaconf ⚙️ Configs for dev/test/prod environments
• Ruff 🪶 Super-fast code linting and cleanup
• Justfile 🪄 Short commands for complex tasks
• Cache Decorator ⚡ Speed up functions with Redis caching

📂 Project Structure

The fully-featured generated project can be found in the example/ directory.

Below is the folder structure of the generated project:

.
├── bot                          # Main directory for the bot's source code
│   ├── cache                    # Contains caching-related modules
│   │   ├── redis.py             # Module for Redis-based caching functionality
│   │   └── serialization.py     # Handles serialization and deserialization for cached data
│   │   
│   ├── core                     # Core components of the bot
│   │   ├── loader.py            # Initializes and loads core components of the bot
│   │   └── settings.py          # Configuration and settings for the bot
│   │   
│   ├── database                 # Database-related modules and models
│   │   ├── models               # Directory for database model definitions
│   │   │   ├── base.py          # Base class for database models
│   │   │   └── user.py          # User table model
│   │   └── database.py          # Database connection
│   │   
│   ├── dialogs                  # Dialog flow and interaction logic
│   │   └── example              # Example implementation of dialogs
│   │       ├── dialogs.py       # Defines dialogs
│   │       ├── getters.py       # Retrieves data required for dialogs
│   │       └── handlers.py      # Handles user interactions within dialogs
│   │   
│   ├── filters/                 # Custom filters for handling specific bot commands or messages
│   │   
│   ├── handlers                 # General handlers for bot events
│   │   └── start.py             # Handler for the /start command
│   │   
│   ├── keyboards                # Defines inline and reply keyboards for user interaction
│   │   └── inline               # Inline keyboards
│   │   
│   ├── middleware               # Middleware modules to extend bot behavior
│   │   ├── analytics.py         # Middleware to identify user for analytics
│   │   ├── database.py          # Middleware to manage database interactions during events
│   │   ├── dependency.py        # Dependency injection middleware for shared resources
│   │   ├── logger.py            # Middleware to log events
│   │   ├── throttling.py        # Middleware to handle rate-limiting of requests
│   │   └── user_register.py     # Add user to DB on /start
│   │   
│   ├── services/                # Auxiliary services with business logic
│   │   └── user.py              # User CRUD and helpers
│   │   
│   ├── states/                  # FSM states
│   │   └── example.py           # Example states
│   │   
│   ├── __main__.py              # Entry point to run the bot application
│   └── commands.py              # Commands setup
│   
├── locales                      # Translations (Fluent `.ftl` files)
│   └── en
│       └── LC_MESSAGES
│           └── bot.ftl          # English texts (add more locales similarly)
│   
├── migrations                   # Database migration files (managed by Alembic)
│   ├── versions/                # Directory containing individual migration scripts
│   │   └── add_users_table.py # Creates users table
│   ├── env.py                   # Alembic environment configuration file
│   └── script.py.mako           # Template for generating new migration scripts
│   
├── .dockerignore                # Specifies files and directories to ignore in Docker builds
├── .gitignore                   # Specifies files and directories to ignore in Git version control
├── .github
│   └── dependabot.yml           # Automatic dependency updates
├── .python-version              # Python version specification file for version managers like pyenv
├── .env                         # Environment variable settings file
├── .template.env                # Template file for environment variables
├── alembic.ini                  # Alembic configuration file for database migrations
├── compose.yaml                 # Docker Compose configuration file for multi-container setups
├── Dockerfile                   # Instructions to build a Docker image for the application
├── entrypoint.sh                # Script executed as the container's entry point 
├── justfile                     # Task runner configuration file (for `just` command automation)
├── pyproject.toml               # Python project metadata and dependencies configuration (PEP-518)
├── README.md                    # Documentation readme file describing the project
└── uv.lock                      # Lock file generated by a dependency manager

📖 Usage

Before using the Copier Telegram Bot template, ensure you have the following installed:

• Copier: Refer to the installation guide
• Copier Templates Extensions: Refer to the repository for installation instructions

Once these prerequisites are installed, you're ready to use the template!

copier copy --trust -r HEAD gh:TimNekk/copier-telegram-bot ~/path/to/your/project

Copier will ask you a lot of questions. Answer them to properly generate the template.

🗺️ Roadmap

Help shape the future! Planned improvements:

• Testing ✅ Add testing framework
• Flake8 / wemake 🧹 Alternative strict linting for code quality fans
• Admin Role 🔒 Add admin filter
• Commands i18n 🌐 Add i18n support for bot commands

Got ideas? Star ⭐ the repo or open an issue to collaborate! 🚀

⭐ Star History

👷 Contributing

• For a small change, just send a PR.
• For bigger changes open an issue for discussion before sending a PR.
• PR should have:
  • Test case
  • Documentation
  • Example (If it makes sense)

📝 License

Distributed under the Apache License 2.0. See LICENSE for more information.