pytmbot

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.

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

💡 Key Features

🐳 Docker Management

Efficient management of Docker containers (start, stop, restart, etc.)
Monitor and retrieve real-time status of running and stopped containers
Access and search detailed container logs
Retrieve, inspect, and manage Docker images, including tag information and metadata
Seamless inline query handling for direct container management via Telegram
NEW: Docker image update checking: Manually check for newer image versions by comparing local tags with those available on Docker Hub, helping ensure that your containers can be updated when needed

🖥️ 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.