Aiogram Base App 🚀

A lightweight and ready-to-use template for developing a Telegram bot using Aiogram. Get started in minutes!

---

🌟 Why Choose This Template?

This starter kit is your fast track to building powerful Telegram bots with Aiogram. Forget about:

• 🔧 Routine database setup
• ⚙️ Complex environment configuration
• 📂 Wasting time on project initialization and structure

---

✨ Core Tools

• 🛠️ Type-safe code with Mypy for reliable type checking
• 🧼 Clean code thanks to linter and formatter Ruff
• 📦 Dependency management with Poetry for convenience
• 🗃️ High-performance database using asynchronous SQLAlchemy and Asyncpg for PostgreSQL
• 🔄 Simple database migrations with Alembic
• ⚡ Fast caching with Redis for reliable FSM (storage)
• ⚙️ Environment variable management with Pydantic-settings
• 📁 Asynchronous file operations via Aiofiles for efficient handling
• 🛡️ Code quality control with Pre-commit hooks and Ruff for clean commits
• ✅ Tests with pytest to test your code
• 🐳 Docker image for:
  • PostgreSQL
  • Redis

---

Requirements

• 🐍 Python 3.12+
• 📦 Poetry (optional, for dependency management)
• 🐳 Docker (optional, for running Postgres and Redis)

---

Installation

1. Clone the Repository 📥

• Via HTTPS:

  git clone https://github.com/eugeneliukindev/Aiogram-Base-App.git

• Via SSH (recommended):

  git clone git@github.com:eugeneliukindev/Aiogram-Base-App.git

2. Install Dependencies ➕

• Using Poetry (recommended):

  • Full installation:

    poetry install

  • Install only main dependencies:

    poetry install --only main

• Using pip:

  pip install -r requirements.txt

---

3. Configure Environment Variables 🔑

Replace environment variables from .env-template with .env

---

4. Launching Docker containers 🐳

docker compose --profile default up -d 

5. Alembic Migrations 🔄

Apply existing database migrations using Alembic:

alembic upgrade head

---

6. Run the Bot 🚀

python main.py

---

Development Tools 🛠️

• Run mypy . for type checking
• Run ruff check . for linting
• Run ruff format . for code formatting
• Run docker compose --profile test up -d & pytest to run tests

---

Additional Notes 📌

• Important Note About .env ⚠️

  The .env file is used to store sensitive data such as database settings, tokens, etc. For demonstration purposes, it is not added to .gitignore. For security, it is strongly recommended to add .env to .gitignore to avoid accidentally pushing sensitive data to the repository:

  echo ".env" >> .gitignore

• Pre-commit Hook Initialization

  If you've installed the dev dependencies and included pre-commit, activate it with:

  pre-commit install

• Removing unnecessary files 🗑️

  Most likely, these files and directories will be unnecessary in your project and can be safely deleted:

  • README.md
  • docs

---

---

Contributing 🤝

We welcome any improvements! To contribute:

1. Fork the repository
2. Create a new feature branch (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -m 'Add YourFeature')
4. Push the branch to the repository (git push origin feature/YourFeature)
5. Open a Pull Request

---

License 📄

This project is licensed under the MIT License. See LICENSE for details.

---

Happy coding! 🎉 If you have questions or need help, open an issue in the repository.