Skip to content

Latest commit

 

History

History
135 lines (97 loc) · 7.15 KB

README.md

File metadata and controls

135 lines (97 loc) · 7.15 KB
Raw

pyTMbot

pyTMbot is a versatile Telegram bot designed for managing Docker containers, monitoring server status, and extending its functionality through a modular plugin system. The bot supports both polling and webhook modes, offering flexibility based on your deployment requirements. Additionally, pyTMbot can be deployed either directly on the host machine or within a Docker container, providing flexibility in infrastructure setup.

Security Rating Vulnerabilities Quality Gate Status Bugs Maintainability Rating Code Smells Duplicated Lines (%) Codacy Badge

pyTMbot leverages the pyTelegramBotAPI, psutil, and docker-py libraries to provide robust Docker and server management tools.

💡 Key Features

🐳 Docker Management

  • Manage Docker containers (start, stop, restart, etc.)
  • View and monitor the status of running and stopped containers
  • Access and search container logs
  • Retrieve and inspect Docker images
  • Inline query handling for managing containers directly from Telegram

🖥️ Local Server Monitoring

  • Load average details and monitoring
  • Summary of memory and swap usage
  • Real-time sensor data
  • Process summary and control
  • Uptime information
  • Network and file system information

🔌 Plugin System

  • Extend functionality through custom plugins with simple configuration.
  • Example plugins:
    • Monitor Plugin: Monitor CPU, memory, temperature (only for Linux), disk usage, and detect changes in Docker containers and images. The plugin sends notifications for various monitored parameters, including new containers and images, ensuring timely awareness of system status.
    • 2FA Plugin: Two-factor authentication for added security using QR codes and TOTP.
    • Outline VPN Plugin: Monitor your Outline VPN server directly from Telegram.

Refer to plugins.md for more information on adding and managing plugins.

🔖 Additional Features

  • Integrated bot update check: /check_bot_updates
  • Emoji support for improved user interaction 😎
  • Templated response system powered by Jinja2
  • Extensive logging through Docker log aggregators

🕸 Requirements

Starting from version 0.9.0, pyTMbot can run either directly on the host machine or in a Docker container. Both deployment methods provide full functionality, but there are slight differences in system access depending on the environment:

  • Host machine deployment: Direct access to system resources like CPU, memory, and sensors. Recommended for cases where precise and real-time system monitoring is critical.
  • Docker container deployment: Ideal for isolated environments or multi-bot setups. Certain low-level system access may be restricted due to container isolation, but Docker management and most server monitoring features remain fully functional.

The bot supports two operational modes:

  • Polling Mode: Simplified setup with no need for HTTPS or a static IP address. Recommended for small-scale or development deployments.
  • Webhook Mode: Optimized for real-time updates with reduced latency. Suitable for production environments, typically requiring an HTTPS server and a valid domain.

To simplify the installation process, we provide an install.sh script that handles the setup, regardless of whether you choose to run pyTMbot on a host machine or within a Docker container. For full instructions on installation and configuration, refer to the installation section.

🔌 Installation and Setup

Refer to installation.md for full instructions on setting up the bot in your environment.

🛡 Security

pyTMbot comes with security-first features, such as:

  • Superuser Role: Manage Docker containers securely.
  • TOTP 2FA Support: Secure sensitive actions with time-based OTPs and QR code generation.
  • Access Control Middleware: Manage bot access using a customizable list of admin IDs.
  • Rate Limiting Middleware: To protect against DoS (Denial-of-Service) attacks, pyTMbot integrates middleware that limits the number of requests allowed from a single user or IP address within a specified time frame. This prevents abuse while ensuring smooth performance under heavy load.

Learn more about the security measures in our detailed security guide.

📈 Roadmap

To learn more about planned features and future updates, check the roadmap.

🐋 Docker Hub

You can find the official Docker image on Docker Hub:

GitHub Release Docker Pulls Docker Image Size Github last-commit

Head to the Docker Hub repository for more details.

📚 Documentation

🧬 Contributors

📜 License

MIT License

This project is licensed under the MIT License – see the LICENSE file for details.