🤖 Linux Server Admin Bot

Telegram bot for monitoring Ubuntu servers. Monitor system resources and receive automated alerts - all from Telegram.

✨ Features

📊 System Monitoring

• CPU: Real-time usage, per-core breakdown, frequency, load average
• Memory: RAM and swap usage with detailed breakdown
• Disk: Root partition space usage
• Network: Interface statistics, traffic monitoring
• Processes: Top CPU-consuming processes

🐳 Docker Management

• Paginated container list (10 per page)
• Container detail view with CPU, memory, IP, ports
• Start, Stop, Restart containers directly from Telegram
• Container status with health indicators
• Graceful detection when Docker is not available

📈 Visualizations

• Beautiful matplotlib charts for all metrics
• CPU usage per core
• Memory distribution pie charts
• Disk usage visualization
• Process resource graphs

🔔 Automated Alerts

• Configurable thresholds for CPU, RAM, and disk
• Automatic notifications when limits exceeded
• Smart cooldown to prevent spam
• Alert severity levels (info, warning, critical)

🔒 Security

• User whitelist authentication
• Rate limiting per user
• Comprehensive logging
• Host PID namespace with restricted capabilities (read-only process access)

🚀 Quick Start

Prerequisites

• Ubuntu server (18.04+)
• Docker and Docker Compose
• Telegram Bot Token (create one)
• Your Telegram User ID (get it)

Installation

1. Clone the repository

git clone https://github.com/artcc/linux-server-admin-bot.git
cd linux-server-admin-bot

2. Configure environment

cp .env.example .env
nano .env

Edit .env with your values:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321

CPU_ALERT_THRESHOLD=80
MEMORY_ALERT_THRESHOLD=80
DISK_ALERT_THRESHOLD=90

3. Create logs directory with correct permissions

mkdir -p logs
sudo chown -R 1000:1000 logs
sudo chmod -R 775 logs

4. Build and run with Docker Compose

docker-compose up -d

5. Check logs

docker-compose logs -f

6. Start chatting with your bot on Telegram!

📖 Usage

🎨 Interactive Menu

The bot features a beautiful interactive menu with inline keyboard buttons for easy navigation:

• Main Menu: Access all features with a single tap
• System Monitoring: CPU, Memory, Disk, Network, Processes
• Quick Navigation: Back buttons and menu shortcuts

Just type /start to see the interactive menu!

Available Commands

Basic

• /start - Welcome message with interactive menu
• /help - Show all available commands
• /status - Overall system status summary

System Monitoring

• /cpu - Detailed CPU information with chart
• /memory - Memory usage with visualization
• /disk - Disk space usage
• /top - Top processes by CPU usage
• /network - Network interface statistics
• /temp - System temperature sensors
• /uptime - System uptime and logged users
• /services - Systemd services status

Docker

• /docker - Docker container management menu

Alerts

• /alerts - View alert configuration and active alerts

Info

• /author - Bot author information

🏗️ Architecture

linux-server-admin-bot/
├── bot/
│   ├── handlers/             # Command handlers
│   │   ├── basic.py          # Start, help, alerts
│   │   ├── system.py         # System monitoring commands
│   │   ├── docker.py         # Docker management commands
│   │   └── callbacks.py      # Inline keyboard callbacks
│   ├── services/             # Business logic
│   │   ├── system_monitor.py # psutil wrapper
│   │   ├── alert_manager.py  # Alert system
│   │   └── docker_manager.py # Docker container management
│   ├── monitors/             # Background tasks
│   │   └── health_monitor.py # Periodic health checks
│   ├── models/               # Data models
│   │   └── metrics.py        # Dataclasses for metrics
│   └── utils/                # Utilities
│       ├── decorators.py     # Auth, rate limiting, logging
│       ├── formatters.py     # Message formatting
│       ├── keyboards.py      # Inline keyboard layouts
│       └── charts.py         # Chart generation
├── config/                   # Configuration
│   ├── settings.py           # Pydantic settings
│   ├── constants.py          # Constants and enums
│   └── logger.py             # Logging setup
├── tests/                    # Unit tests
├── docs/                     # Documentation
├── main.py                   # Application entry point
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Docker Compose config
└── requirements.txt          # Python dependencies

Design Principles

• Separation of Concerns: Clear separation between handlers, services, and utilities
• Type Safety: Full type hints and Pydantic validation
• Testability: Dependency injection and comprehensive tests
• Security: Authorization, rate limiting, and audit logging
• Observability: Structured logging and error handling
• Scalability: Async/await patterns for concurrent operations

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
TELEGRAM_BOT_TOKEN	Telegram Bot API token	✅ Yes	-
TELEGRAM_ALLOWED_USER_IDS	Comma-separated user IDs	✅ Yes	-
CPU_ALERT_THRESHOLD	CPU usage alert threshold (%)	❌ No	80
MEMORY_ALERT_THRESHOLD	Memory usage alert threshold (%)	❌ No	80
DISK_ALERT_THRESHOLD	Disk usage alert threshold (%)	❌ No	90
ALERT_CHECK_INTERVAL	Alert check interval (seconds)	❌ No	300
ALERT_COOLDOWN	Alert cooldown period (seconds)	❌ No	600
RATE_LIMIT_CALLS	Max calls per period	❌ No	10
RATE_LIMIT_PERIOD	Rate limit period (seconds)	❌ No	60
LOG_LEVEL	Logging level	❌ No	INFO

Docker Volumes

The bot requires access to host system resources:

volumes:
  - /proc:/host/proc:ro                      # System metrics
  - /sys:/host/sys:ro                         # System information
  - /var/run/docker.sock:/var/run/docker.sock:ro  # Docker management (optional)

Note: The Docker socket mount is optional. If not mounted, the Docker menu will show that Docker is not available.

🎨 Bot Avatar

You can use the official bot avatar for your own instance:

Download: linux-server-admin-bot.png

To set this image as your bot's profile picture:

1. Download the image from the link above
2. Open @BotFather on Telegram
3. Send /setuserpic
4. Select your bot
5. Upload the downloaded image

🧪 Development

Local Setup

1. Create virtual environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

2. Install dependencies

pip install -r requirements.txt

3. Run locally

python main.py

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=bot --cov-report=html

# Run specific test file
pytest tests/test_system_monitor.py

Code Quality

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy bot/ config/

🐛 Troubleshooting

Bot doesn't respond

• Check logs: docker-compose logs -f
• Verify bot token is correct
• Ensure your user ID is in TELEGRAM_ALLOWED_USER_IDS

High memory usage

• Adjust resource limits in docker-compose.yml
• Increase alert check interval
• Reduce chart DPI in settings

Temperature sensors not working

• Install lm-sensors: sudo apt install lm-sensors
• Run sensor detection: sudo sensors-detect

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

🙏 Acknowledgments

• python-telegram-bot - Telegram Bot framework
• psutil - System monitoring
• docker-py - Docker SDK for Python
• matplotlib - Visualization library

📧 Support

For support, open an issue on GitHub.

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Made with ❤️ for system administrators

_{100% built with GitHub Copilot (Claude Opus 4.5)
Arturo Carretero Calvo — 2026}