{"id":24489685,"url":"https://github.com/timnekk/copier-telegram-bot","last_synced_at":"2025-05-08T03:34:03.821Z","repository":{"id":273206980,"uuid":"918990879","full_name":"TimNekk/copier-telegram-bot","owner":"TimNekk","description":"🚀 Copier Template for Telegram Bot using Aiogram, Postgres, Redis, Docker, Coolify Ready","archived":false,"fork":false,"pushed_at":"2025-03-08T11:25:22.000Z","size":122,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T12:24:37.213Z","etag":null,"topics":["aiogram","copier-template","database","docker","docker-compose","poerty","postgresql","pydantic","python","redis","ruff","sqlalchemy","telegram","telegram-bot","telegrambot","template","uv"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimNekk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-19T12:33:58.000Z","updated_at":"2025-03-08T11:25:20.000Z","dependencies_parsed_at":"2025-02-07T11:28:43.785Z","dependency_job_id":"653248b4-b713-4531-ac09-eb284393be2b","html_url":"https://github.com/TimNekk/copier-telegram-bot","commit_stats":null,"previous_names":["timnekk/copier-telegram-bot"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimNekk%2Fcopier-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimNekk%2Fcopier-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimNekk%2Fcopier-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimNekk%2Fcopier-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimNekk","download_url":"https://codeload.github.com/TimNekk/copier-telegram-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243668774,"owners_count":20328138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","copier-template","database","docker","docker-compose","poerty","postgresql","pydantic","python","redis","ruff","sqlalchemy","telegram","telegram-bot","telegrambot","template","uv"],"created_at":"2025-01-21T17:15:22.571Z","updated_at":"2025-05-08T03:34:03.812Z","avatar_url":"https://github.com/TimNekk.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1 \"\u003e\u003ccode\u003eTelegram Bot Template\u003c/code\u003e\u003c/h1\u003e\n    \u003cdiv\u003e\n        \u003ca href=\"https://github.com/copier-org/copier\"\u003e\n            \u003cpicture\u003e\n               \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-black.json\u0026style=for-the-badge\u0026labelColor=010409\u0026color=1e242a\" /\u003e\n               \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-black.json\u0026style=for-the-badge\u0026labelColor=010409\u0026color=f0f1f2\" /\u003e\n               \u003cimg alt=\"Copier\" /\u003e\n             \u003c/picture\u003e\n        \u003c/a\u003e\n        \u003cpicture\u003e\n           \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/-Python 3.9 — 3.13-1e242a?style=for-the-badge\u0026logoColor=white\u0026labelColor=3776AB\u0026logo=python\" /\u003e\n           \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://img.shields.io/badge/-Python 3.9 — 3.13-f0f1f2?style=for-the-badge\u0026logoColor=white\u0026labelColor=3776AB\u0026logo=python\" /\u003e\n           \u003cimg alt=\"Python 3.9 - 3.13\" /\u003e\n         \u003c/picture\u003e\n        \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\n            \u003cpicture\u003e\n               \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/-Linted by Ruff-1e242a?style=for-the-badge\u0026logoColor=30173d\u0026labelColor=D7FF64\u0026logo=ruff\" /\u003e\n               \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://img.shields.io/badge/-Linted by Ruff-f0f1f2?style=for-the-badge\u0026logoColor=30173d\u0026labelColor=D7FF64\u0026logo=ruff\" /\u003e\n               \u003cimg alt=\"Linted by Ruff\" /\u003e\n             \u003c/picture\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://github.com/TimNekk/copier-telegram-bot/blob/main/LICENSE.md\"\u003e\n            \u003cpicture\u003e\n               \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/-Apache License 2.0-1e242a?style=for-the-badge\u0026logoColor=1e242a\u0026labelColor=white\u0026logo=googledocs\" /\u003e\n               \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://img.shields.io/badge/-Apache License 2.0-f0f1f2?style=for-the-badge\u0026logoColor=white\u0026labelColor=1f2328\u0026logo=googledocs\" /\u003e\n               \u003cimg alt=\"Apache License 2.0\" /\u003e\n             \u003c/picture\u003e\n        \u003c/a\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\n## 🚀 Quickstart\n\nEnsure [uv](https://docs.astral.sh/uv/getting-started/installation/) is installed, then create a new Telegram bot project with:\n\n```bash\nuvx --with copier-templates-extensions copier copy --trust -r HEAD gh:TimNekk/copier-telegram-bot ~/path/to/your/project\n```\n\n## ✨ Features\n\nBuilt with [Copier](https://copier.readthedocs.io/), this template lets you toggle features during setup - choose what you need and generate files instantly! Ready for [Docker](https://www.docker.com/) 🐳 and [Coolify](https://coolify.io/) ☁️ deployment.\n\n#### Core Infrastructure\n\n- [x] [**`Docker Compose`**](https://docs.docker.com/compose/) 🐳 Launch bot + services with one command\n- [x] [**`Python 3.9–3.13`**](https://www.python.org/) 🐍 Choose your Python version easily\n- [x] [**`uv`**](https://docs.astral.sh/uv/) 🚀 Fast dependency management powered by Rust\n- [x] [**`Poetry`**](https://python-poetry.org/) 📦 Manage dependencies safely with virtual environments\n- [x] [**`pip`**](https://pip.pypa.io/) 📜 Classic Python package installer\n\n#### Telegram Bot Framework\n\n- [x] [**`Aiogram`**](https://docs.aiogram.dev/) ⚡ Modern async bot framework with state management\n- [x] [**`Aiogram Dialog`**](https://github.com/Tishka17/aiogram_dialog) 🖼️ Create menus and interactive interfaces\n- [x] [**`Redis`**](https://redis.io/) ❤️ Keep bot data safe between restarts\n\n#### Database \u0026 ORM\n\n- [x] [**`PostgreSQL`**](https://www.postgresql.org/) 🐘 Powerful database for complex projects\n- [x] [**`SQLAlchemy`**](https://www.sqlalchemy.org/) 🛠️ Work with databases using Python code\n- [x] [**`Alembic`**](https://alembic.sqlalchemy.org/) ⏳ Track and apply database changes easily\n\n#### Middlewares\n\n- [x] [**`Dependency Injection`**](https://docs.aiogram.dev/en/latest/dispatcher/middlewares.html) 💉 Share tools/data across bot handlers\n- [x] [**`Throttling`**](https://docs.aiogram.dev/en/latest/dispatcher/middlewares.html) 🛑 Stop spam with automatic speed limits\n- [x] [**`Database Sessions`**](https://docs.sqlalchemy.org/en/20/orm/session_basics.html) ♻️ Auto-manage database connections\n- [x] [**`Loguru`**](https://github.com/Delgan/loguru) 📜 Simple logging with colors and fun\n\n#### Tooling\n\n- [x] [**`Pydantic Settings`**](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) ✅ Safe config management with type checking\n- [x] [**`Dynaconf`**](https://www.dynaconf.com/) ⚙️ Configs for dev/test/prod environments\n- [x] [**`Ruff`**](https://docs.astral.sh/ruff/) 🪶 Super-fast code linting and cleanup\n- [x] [**`Justfile`**](https://just.systems/) 🪄 Short commands for complex tasks\n- [x] [**`Cache Decorator`**](https://pypi.org/project/orjson/) ⚡ Speed up functions with Redis caching\n\n## 📂 Project Structure\n\nThe **fully-featured** generated project can be found in the [example/](./example) directory.\n\nBelow is the folder structure of the generated project:\n\n```sh\n.\n├── bot                          # Main directory for the bot's source code\n│   ├── cache                    # Contains caching-related modules\n│   │   ├── redis.py             # Module for Redis-based caching functionality\n│   │   └── serialization.py     # Handles serialization and deserialization for cached data\n│   │   \n│   ├── core                     # Core components of the bot\n│   │   ├── loader.py            # Initializes and loads core components of the bot\n│   │   └── settings.py          # Configuration and settings for the bot\n│   │   \n│   ├── database                 # Database-related modules and models\n│   │   ├── models               # Directory for database model definitions\n│   │   │   └── base.py          # Base class for database models\n│   │   └── database.py          # Database connection\n│   │   \n│   ├── dialogs                  # Dialog flow and interaction logic\n│   │   └── example              # Example implementation of dialogs\n│   │       ├── dialogs.py       # Defines dialogs\n│   │       ├── getters.py       # Retrieves data required for dialogs\n│   │       └── handlers.py      # Handles user interactions within dialogs\n│   │   \n│   ├── filters/                 # Custom filters for handling specific bot commands or messages\n│   │   \n│   ├── handlers                 # General handlers for bot events\n│   │   └── start.py             # Handler for the /start command\n│   │   \n│   ├── keyboards                # Defines inline and reply keyboards for user interaction\n│   │   ├── inline               # Inline keyboards\n│   │   └── default_commands.py  # Defualt commands setup\n│   │   \n│   ├── middleware               # Middleware modules to extend bot behavior\n│   │   ├── database.py          # Middleware to manage database interactions during eventxs\n│   │   ├── dependency.py        # Dependency injection middleware for shared resources\n│   │   ├── logger.py            # Middleware to log events\n│   │   └── throttling.py        # Middleware to handle rate-limiting of requests\n│   │   \n│   ├── services/                # Auxiliary services with business logic\n│   │   \n│   ├── __main__.py              # Entry point to run the bot application\n│   └── states.py                # FMS states\n│   \n├── migrations                   # Database migration files (managed by Alembic)\n│   ├── versions/                # Directory containing individual migration scripts\n│   ├── env.py                   # Alembic environment configuration file\n│   └── script.py.mako           # Template for generating new migration scripts\n│   \n├── .dockerignore                # Specifies files and directories to ignore in Docker builds\n├── .gitignore                   # Specifies files and directories to ignore in Git version control\n├── .python-version              # Python version specification file for version managers like pyenv\n├── .env                         # Environment variable settings file\n├── .template.env                # Template file for environment variables\n├── alembic.ini                  # Alembic configuration file for database migrations\n├── compose.yaml                 # Docker Compose configuration file for multi-container setups\n├── Dockerfile                   # Instructions to build a Docker image for the application\n├── entrypoint.sh                # Script executed as the container's entry point \n├── justfile                     # Task runner configuration file (for `just` command automation)\n├── pyproject.toml               # Python project metadata and dependencies configuration (PEP-518)\n├── README.md                    # Documentation readme file describing the project\n└── uv.lock                      # Lock file generated by a dependency manager\n```\n\n## 📖 Usage\n\nBefore using the **Copier Telegram Bot** template, ensure you have the following installed:\n\n- **Copier**: Refer to the [installation guide](https://copier.readthedocs.io/en/latest/#installation).\n- **Copier Templates Extensions**: Refer to the [repository](https://github.com/copier-org/copier-templates-extensions?tab=readme-ov-file#installation) for installation instructions.\n\nOnce these prerequisites are installed, you're ready to use the template!\n\n```bash\ncopier copy --trust -r HEAD gh:TimNekk/copier-telegram-bot ~/path/to/your/project\n```\n\nCopier will ask you a lot of questions. Answer them to properly generate the template.\n\n## 🗺️ Roadmap\n\nHelp shape the future! Planned improvements:\n\n- [ ] [**`Bot Internationalization`**](https://docs.aiogram.dev/en/latest/dispatcher/i18n.html) 🌐 Support multiple languages for global audiences\n- [ ] [**`Prompts Internationalization`**](https://github.com/aiogram/aiogram) 📋 Translate copier prompts\n- [ ] [**`Dependabot`**](https://github.com/dependabot) 🤖 Add dependencies auto-update to generated project for security and freshness\n- [ ] [**`Testing`**](https://docs.pytest.org/) ✅ Add testing framework\n- [ ] [**`Flake8`**](https://flake8.pycqa.org/) / [**`wemake`**](https://wemake-python-styleguide.readthedocs.io/en/latest/) 🧹 Alternative strict linting for code quality fans\n\n*Got ideas? Star ⭐ the repo or open an issue to collaborate!* 🚀\n\n## ⭐ Star History\n\n\u003ca href=\"https://star-history.com/#TimNekk/copier-telegram-bot\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=TimNekk/copier-telegram-bot\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=TimNekk/copier-telegram-bot\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=TimNekk/copier-telegram-bot\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## 👷 Contributing\n\n- For a small change, just send a PR.\n- For bigger changes open an issue for discussion before sending a PR.\n- PR should have:\n  - Test case\n  - Documentation\n  - Example (If it makes sense)\n\n## 📝 License\n\nDistributed under the Apache License 2.0. See [`LICENSE`](./LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimnekk%2Fcopier-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimnekk%2Fcopier-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimnekk%2Fcopier-telegram-bot/lists"}