Skip to content
ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆ

TimNekk/copier-telegram-bot has 49 GitHub stars and 5 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-21 07:41 UTC. Last push 2026-10-30.

ใ“ใฎๆ•ฐๅ€คใฎๆธฌใ‚Šๆ–น

่จˆๆธฌใ—ใŸใ‚นใ‚ฟใƒผๅข—ๅŠ 

24ๆ™‚้–“
0
7ๆ—ฅ้–“
0
15ๆ—ฅ้–“
ๅฑฅๆญดใ‚’ๅŽ้›†ไธญ
1ใ‹ๆœˆ
ๅฑฅๆญดใ‚’ๅŽ้›†ไธญ

ๆœŸ้–“ใ”ใจใฎ็ด”ๅข—ๆ•ฐใงใ™ใ€‚ๆœŸ้–“ใฏ้‡่ค‡ใ—ใฆใŠใ‚Šใ€ๆ—ฅๅˆฅใฎๅ€คใงใฏใ‚ใ‚Šใพใ›ใ‚“ใ€‚ๆœช่จˆๆธฌใฎๅ€คใฏ็ฉบๆฌ„ใงใ™ใ€‚ใ‚นใ‚ฟใƒผๆ•ฐใฏๆณจ็›ฎๅบฆใฎๆŒ‡ๆจ™ใงใ‚ใ‚Šใ€ๅ“่ณชใฎไฟ่จผใงใฏใ‚ใ‚Šใพใ›ใ‚“ใ€‚

ๆฆ‚่ฆ

๐Ÿš€ Copier Template for Telegram Bot using Aiogram, Postgres, Redis, Docker, Coolify Ready

ใƒ‡ใƒผใ‚ฟ

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.14 ๐Ÿ 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

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:

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.