308 lines
8.7 KiB
Markdown
308 lines
8.7 KiB
Markdown
# Pterodactyl Discord Bot
|
|
|
|
|
|
|
|
A feature-rich Discord bot for monitoring and managing Pterodactyl game servers through Discord, providing real-time status monitoring and control capabilities with an intuitive interface.
|
|
|
|
## Table of Contents
|
|
- [Features](#features)
|
|
- [Architecture Overview](#architecture-overview)
|
|
- [Installation](#installation)
|
|
- [Traditional Installation](#traditional-installation)
|
|
- [Docker Installation](#docker-installation)
|
|
- [Configuration](#configuration)
|
|
- [Environment Variables](#environment-variables)
|
|
- [Configuration File](#configuration-file)
|
|
- [Usage](#usage)
|
|
- [First Run Setup](#first-run-setup)
|
|
- [Bot Commands](#bot-commands)
|
|
- [Embed System](#embed-system)
|
|
- [Permissions](#permissions)
|
|
- [Logging System](#logging-system)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Development](#development)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
- **Real-time Server Monitoring**: Auto-updating embeds showing server status (online/offline) and detailed resource usage
|
|
- **Power Management**: Start, stop, and restart servers directly from Discord with button controls
|
|
- **Connection Information**: One-click display of server IP addresses and ports
|
|
- **Multi-channel Support**: Status embeds can be placed in any channel with proper permissions
|
|
|
|
### Intelligent Updates
|
|
- **State Change Detection**: Embeds update immediately when server power state changes
|
|
- **Resource Thresholds**: CPU usage changes >50% trigger updates
|
|
- **Optimized API Calls**: Minimizes requests to the Discord API
|
|
|
|
### Access Control
|
|
- **Guild Restriction**: Operates only in specified Discord server
|
|
- **Role-based Permissions**: "Game Server User" role required for interactions
|
|
- **Admin Commands**: Special commands restricted to server administrators
|
|
|
|
### Reliability Features
|
|
- **Persistent Storage**: Remembers embed locations between bot restarts
|
|
- **Error Handling**: Comprehensive error recovery and logging
|
|
- **Rate Limit Protection**: Built-in delays between API calls
|
|
|
|
## Architecture Overview
|
|
|
|
The bot is built with several key components:
|
|
|
|
1. **PterodactylAPI Class**: Handles all communication with the Pterodactyl Panel API
|
|
2. **ServerStatusView Class**: Manages the interactive Discord UI with control buttons
|
|
3. **PterodactylBot Class**: Main bot class that orchestrates all operations
|
|
4. **Background Task**: Regularly checks server status and updates embeds when needed
|
|
5. **Configuration System**: Validates and manages all settings from config.ini
|
|
|
|
The system uses aiohttp for asynchronous HTTP requests and discord.py for Discord interactions.
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
- Python 3.8 or higher **or** Docker
|
|
- Discord bot token with proper permissions
|
|
- Pterodactyl panel with API access
|
|
- Server with both Client and Application API keys
|
|
|
|
### Traditional Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://git.serendipity.systems/yourusername/pterodactyl-discord-bot.git
|
|
cd pterodactyl-discord-bot
|
|
```
|
|
|
|
2. Install required dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Create and configure your `config.ini` file (see [Configuration](#configuration) section)
|
|
|
|
4. Run the bot:
|
|
```bash
|
|
python pterodisbot.py
|
|
```
|
|
|
|
### Docker Installation
|
|
|
|
1. Build the Docker image:
|
|
```bash
|
|
docker build -t pterodactyl-bot .
|
|
```
|
|
|
|
2. Create a directory for configuration:
|
|
```bash
|
|
mkdir -p bot-config
|
|
```
|
|
|
|
3. Create a `config.ini` file in the `bot-config` directory with your settings
|
|
|
|
4. Run the container with the config mounted:
|
|
```bash
|
|
docker run -d \
|
|
--name pterodactyl-bot \
|
|
-v $(pwd)/bot-config:/app \
|
|
pterodactyl-bot
|
|
```
|
|
|
|
5. For Docker Compose, create a `docker-compose.yml` file:
|
|
```yaml
|
|
services:
|
|
pterodactyl-bot:
|
|
build: .
|
|
container_name: pterodactyl-bot
|
|
volumes:
|
|
- ./bot-config:/app
|
|
restart: unless-stopped
|
|
```
|
|
Then run:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
When using Docker or generating the config automatically, these environment variables are required:
|
|
|
|
- `DISCORD_TOKEN`: Your Discord bot token
|
|
- `ALLOWED_GUILD_ID`: The Discord server ID where the bot should operate
|
|
- `PANEL_URL`: Your Pterodactyl panel URL (must include http:// or https://)
|
|
- `CLIENT_API_KEY`: Pterodactyl client API key (starts with `ptlc_`)
|
|
- `APPLICATION_API_KEY`: Pterodactyl application API key (starts with `ptla_`)
|
|
|
|
### Configuration File
|
|
|
|
The bot uses a `config.ini` file with this structure:
|
|
|
|
```ini
|
|
[Pterodactyl]
|
|
PanelURL = https://your.pterodactyl.panel
|
|
ClientAPIKey = ptlc_yourclientkey
|
|
ApplicationAPIKey = ptla_yourapplicationkey
|
|
|
|
[Discord]
|
|
Token = your.discord.bot.token
|
|
AllowedGuildID = 123456789012345678
|
|
```
|
|
|
|
To generate the config file from environment variables:
|
|
```bash
|
|
python generate_config.py
|
|
```
|
|
|
|
## Usage
|
|
|
|
### First Run Setup
|
|
|
|
1. Invite your bot to your Discord server with these permissions:
|
|
- View Channels
|
|
- Send Messages
|
|
- Embed Links
|
|
- Manage Messages (for embed updates)
|
|
- Use Slash Commands
|
|
|
|
2. Create a "Game Server User" role for users who should control servers
|
|
|
|
3. Use the `/server_status` command to create your first status embed
|
|
|
|
### Bot Commands
|
|
|
|
#### `/server_status [server_name] [channel]`
|
|
Display a server's status embed in the specified channel (or current channel if not specified).
|
|
|
|
**Example:**
|
|
```
|
|
/server_status server_name: "Minecraft Survival" channel: #game-servers
|
|
```
|
|
|
|
#### `/refresh_embeds` (Admin only)
|
|
Force a refresh of all server status embeds. This is useful if embeds become out of sync.
|
|
|
|
### Embed System
|
|
|
|
Status embeds include:
|
|
- Server name and current state (color-coded)
|
|
- Resource usage (when online):
|
|
- CPU percentage
|
|
- Memory usage
|
|
- Disk usage
|
|
- Network activity
|
|
- Interactive buttons:
|
|
- Start (green)
|
|
- Stop (red)
|
|
- Restart (blue)
|
|
- Show Address (grey)
|
|
|
|
Embed locations are stored in `embed_locations.json` and persist between bot restarts.
|
|
|
|
## Permissions
|
|
|
|
The bot implements two levels of access control:
|
|
|
|
1. **Guild Restriction**: Only works in the Discord server specified in `AllowedGuildID`
|
|
2. **Role Requirement**: Users must have the "Game Server User" role to interact with server controls
|
|
|
|
Administrators can use the `/refresh_embeds` command.
|
|
|
|
## Logging System
|
|
|
|
The bot maintains comprehensive logs in two locations:
|
|
|
|
1. **File Logs**: Rotating log files (5MB max, 3 backups) in `pterodactyl_bot.log`
|
|
2. **Console Output**: Real-time logging to stdout
|
|
|
|
Log levels:
|
|
- **DEBUG**: Detailed operational information (API calls, state changes)
|
|
- **INFO**: General operational messages (bot startup, command usage)
|
|
- **WARNING**: Potential issues (missing embeds, API warnings)
|
|
- **ERROR**: Operational failures (API errors, permission issues)
|
|
- **CRITICAL**: Critical failures (configuration errors, startup failures)
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Embeds not updating:**
|
|
- Verify the bot has proper channel permissions
|
|
- Check API keys have correct permissions
|
|
- Use `/refresh_embeds` to reset all embeds
|
|
|
|
**Buttons not working:**
|
|
- Confirm users have the "Game Server User" role
|
|
- Ensure the bot has these permissions:
|
|
- View Channel
|
|
- Send Messages
|
|
- Embed Links
|
|
- Use Slash Commands
|
|
|
|
**API errors:**
|
|
- Double-check your Pterodactyl panel URL
|
|
- Verify API keys are correct and not expired
|
|
- Confirm the server exists in Pterodactyl
|
|
|
|
### Checking Logs
|
|
|
|
For real-time log monitoring:
|
|
```bash
|
|
tail -f pterodactyl_bot.log
|
|
```
|
|
|
|
## Development
|
|
|
|
### Requirements
|
|
- Python 3.8+
|
|
- Poetry (recommended) or pip
|
|
|
|
### Setup
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
```bash
|
|
poetry install
|
|
```
|
|
or
|
|
```bash
|
|
pip install -r requirements.txt -r requirements-dev.txt
|
|
```
|
|
|
|
3. Create a `.env` file with your development environment variables
|
|
|
|
4. Run in development mode:
|
|
```bash
|
|
python pterodisbot.py
|
|
```
|
|
|
|
### Testing
|
|
The project includes unit tests (to be expanded). Run with:
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please follow these guidelines:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/your-feature`)
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
4. Push to the branch (`git push origin feature/your-feature`)
|
|
5. Open a pull request
|
|
|
|
### Coding Standards
|
|
- Follow PEP 8 style guidelines
|
|
- Include type hints for all function signatures
|
|
- Document public methods with docstrings
|
|
- Write tests for new functionality
|
|
|
|
## License
|
|
|
|
This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
**Note**: This bot is designed for single Pterodactyl domain and single Discord guild use. For multi-instance support, significant modifications would be required. |