TimNekk/copier-telegram-bot
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
ใใผใฟREADME.md
ใชใชใธใใซ๐ 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
-
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.