k.eaven/pterodactyl-discord-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand README documentation

Browse Source
This commit is contained in:
Eaven Kimura
2025-07-21 23:26:58 -07:00
parent c1570acc40
commit fe64046fc8
1 changed files with 187 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

259
README.md
View File

@@ -1,43 +1,73 @@
# Pterodactyl Discord Bot # Pterodactyl Discord Bot - Comprehensive Documentation
![Pterodactyl Logo](https://cdn.pterodactyl.io/logos/new/pterodactyl_logo_transparent.png) ![Pterodactyl Logo](https://cdn.pterodactyl.io/logos/new/pterodactyl_logo_transparent.png)
A comprehensive Discord bot for managing Pterodactyl game servers through Discord, providing real-time status monitoring and control capabilities. 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 ## Table of Contents
- [Features](#features) - [Features](#features)
- [Architecture Overview](#architecture-overview)
- [Installation](#installation) - [Installation](#installation)
- [Traditional Installation](#traditional-installation)
- [Docker Installation](#docker-installation)
- [Configuration](#configuration) - [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [Configuration File](#configuration-file)
- [Usage](#usage) - [Usage](#usage)
- [Commands](#commands) - [First Run Setup](#first-run-setup)
- [Embed System](#embed-system) - [Bot Commands](#bot-commands)
- [Embed System](#embed-system)
- [Permissions](#permissions) - [Permissions](#permissions)
- [Logging](#logging) - [Logging System](#logging-system)
- [Troubleshooting](#troubleshooting) - [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing) - [Contributing](#contributing)
- [License](#license) - [License](#license)
## Features ## Features
- **Real-time Server Monitoring**: Auto-updating embeds showing server status and resource usage ### Core Functionality
- **Power Controls**: Start, stop, and restart servers directly from Discord - **Real-time Server Monitoring**: Auto-updating embeds showing server status (online/offline) and detailed resource usage
- **Connection Info**: Display server IP addresses and ports with one click - **Power Management**: Start, stop, and restart servers directly from Discord with button controls
- **Multi-channel Support**: Status embeds can be placed in any channel - **Connection Information**: One-click display of server IP addresses and ports
- **Smart Updates**: Only updates embeds when significant changes occur - **Multi-channel Support**: Status embeds can be placed in any channel with proper permissions
- **Role-based Access Control**: Restrict server controls to users with specific roles
- **Single-guild Operation**: Designed for use in one Discord server to restrict access ### Intelligent Updates
- **Persistent Storage**: Remembers embeds and recreates them between bot restarts - **State Change Detection**: Embeds update immediately when server power state changes
- **Comprehensive Logging**: Detailed logs for all operations and errors - **Resource Thresholds**: CPU usage changes >50% trigger updates
- **Optimized API Calls**: Minimizes unnecessary requests to both Discord and Pterodactyl APIs
### 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 ## Installation
### Prerequisites ### Prerequisites
- Python 3.8 or higher - Python 3.8 or higher **or** Docker
- Discord bot token with proper permissions - Discord bot token with proper permissions
- Pterodactyl panel with API access - Pterodactyl panel with API access
- Server with Client and Application API keys - Server with both Client and Application API keys
### Setup Steps ### Traditional Installation
1. Clone the repository: 1. Clone the repository:
```bash ```bash
@@ -50,16 +80,66 @@ A comprehensive Discord bot for managing Pterodactyl game servers through Discor
pip install -r requirements.txt pip install -r requirements.txt
``` ```
3. Create a `config.ini` file (see [Configuration](#configuration) section) 3. Create and configure your `config.ini` file (see [Configuration](#configuration) section)
4. Run the bot: 4. Run the bot:
```bash ```bash
python pterodisbot.py 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
version: '3'
services:
pterodactyl-bot:
build: .
container_name: pterodactyl-bot
volumes:
- ./bot-config:/app
restart: unless-stopped
```
Then run:
```bash
docker-compose up -d
```
## Configuration ## Configuration
The bot requires a `config.ini` file with the following structure: ### 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 ```ini
[Pterodactyl] [Pterodactyl]
@@ -72,31 +152,29 @@ Token = your.discord.bot.token
AllowedGuildID = 123456789012345678 AllowedGuildID = 123456789012345678
``` ```
### Configuration Details To generate the config file from environment variables:
```bash
- **PanelURL**: Your Pterodactyl panel URL (must include http:// or https://) python generate_config.py
- **ClientAPIKey**: Pterodactyl client API key (starts with `ptlc_`) ```
- **ApplicationAPIKey**: Pterodactyl application API key (starts with `ptla_`)
- **Token**: Your Discord bot token
- **AllowedGuildID**: The Discord server ID where the bot should operate
## Usage ## Usage
Once configured and running, the bot will: ### First Run Setup
1. Connect to your Discord server 1. Invite your bot to your Discord server with these permissions:
2. Sync slash commands - View Channels
3. Begin monitoring your Pterodactyl servers - Send Messages
4. Update status embeds whenever server status changes or CPU usage spikes up/down for more than 10 seconds - Embed Links
5. Create power control buttons for each Pterodactyl server monitored - Manage Messages (for embed updates)
- Use Slash Commands
### First Run 2. Create a "Game Server User" role for users who should control servers
On first run, you'll need to manually create status embeds using the `/server_status` command for each server you want to monitor. 3. Use the `/server_status` command to create your first status embed
## Commands ### Bot Commands
### `/server_status [server_name] [channel]` #### `/server_status [server_name] [channel]`
Display a server's status embed in the specified channel (or current channel if not specified). Display a server's status embed in the specified channel (or current channel if not specified).
**Example:** **Example:**
@@ -104,16 +182,19 @@ Display a server's status embed in the specified channel (or current channel if
/server_status server_name: "Minecraft Survival" channel: #game-servers /server_status server_name: "Minecraft Survival" channel: #game-servers
``` ```
### `/refresh_embeds` (Admin only) #### `/refresh_embeds` (Admin only)
Force a refresh of all server status embeds. This is useful if embeds become out of sync. Force a refresh of all server status embeds. This is useful if embeds become out of sync.
## Embed System ### Embed System
The bot uses persistent interactive embeds with the following features: Status embeds include:
- Server name and current state (color-coded)
- **Dynamic Color Coding**: Running (blue) vs offline (red) - Resource usage (when online):
- **Resource Monitoring**: CPU, memory, disk, and network usage - CPU percentage
- **Interactive Buttons**: - Memory usage
- Disk usage
- Network activity
- Interactive buttons:
- Start (green) - Start (green)
- Stop (red) - Stop (red)
- Restart (blue) - Restart (blue)
@@ -130,60 +211,94 @@ The bot implements two levels of access control:
Administrators can use the `/refresh_embeds` command. Administrators can use the `/refresh_embeds` command.
## Logging ## Logging System
The bot maintains comprehensive logs in two locations: The bot maintains comprehensive logs in two locations:
1. **File Logs**: Rotating log files (5MB max, 3 backups) in `pterodactyl_bot.log` 1. **File Logs**: Rotating log files (5MB max, 3 backups) in `pterodactyl_bot.log`
2. **Console Output**: Real-time logging to stdout 2. **Console Output**: Real-time logging to stdout
Log levels include: Log levels:
- DEBUG: Detailed operational information - **DEBUG**: Detailed operational information (API calls, state changes)
- INFO: General operational messages - **INFO**: General operational messages (bot startup, command usage)
- WARNING: Potential issues - **WARNING**: Potential issues (missing embeds, API warnings)
- ERROR: Operational failures - **ERROR**: Operational failures (API errors, permission issues)
- CRITICAL: Critical failures - **CRITICAL**: Critical failures (configuration errors, startup failures)
## Troubleshooting ## Troubleshooting
### Common Issues ### Common Issues
1. **Embeds not updating**: **Embeds not updating:**
- Check bot has proper permissions in the channel - Verify the bot has proper channel permissions
- Verify API keys are correct and have proper permissions - Check API keys have correct permissions
- Use `/refresh_embeds` to reset all embeds - Use `/refresh_embeds` to reset all embeds
2. **Buttons not working**: **Buttons not working:**
- Ensure users have the "Game Server User" role - Confirm users have the "Game Server User" role
- Verify the bot has proper permissions (View Channel, Send Messages, Embed Links) - Ensure the bot has these permissions:
- View Channel
- Send Messages
- Embed Links
- Use Slash Commands
3. **API errors**: **API errors:**
- Check your Pterodactyl panel URL and API keys - Double-check your Pterodactyl panel URL
- Verify the server exists in Pterodactyl - Verify API keys are correct and not expired
- Confirm the server exists in Pterodactyl
### Checking Logs ### Checking Logs
Always check the log files first when troubleshooting: For real-time log monitoring:
```bash ```bash
tail -f pterodactyl_bot.log 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 ## Contributing
Contributions are welcome! Please follow these guidelines: Contributions are welcome! Please follow these guidelines:
1. Fork the repository 1. Fork the repository
2. Create a feature branch 2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Submit a pull request 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
### Development Setup ### Coding Standards
- Follow PEP 8 style guidelines
1. Install development dependencies: - Include type hints for all function signatures
```bash - Document public methods with docstrings
pip install -r requirements-dev.txt - Write tests for new functionality
```
2. Enable debug logging by modifying the logger configuration in the bot code.
## License ## License
@@ -191,4 +306,4 @@ This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE)
--- ---
**Note**: This bot is designed for use with a single Pterodactyl domain and single Discord server. For multi-domain or multi-guild support, modifications would be required. **Note**: This bot is designed for single Pterodactyl domain and single Discord server use. For multi-instance support, significant modifications would be required.