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)
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
- [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)
- [Commands](#commands)
- [Embed System](#embed-system)
- [First Run Setup](#first-run-setup)
- [Bot Commands](#bot-commands)
- [Embed System](#embed-system)
- [Permissions](#permissions)
- [Logging](#logging)
- [Logging System](#logging-system)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## Features
- **Real-time Server Monitoring**: Auto-updating embeds showing server status and resource usage
- **Power Controls**: Start, stop, and restart servers directly from Discord
- **Connection Info**: Display server IP addresses and ports with one click
- **Multi-channel Support**: Status embeds can be placed in any channel
- **Smart Updates**: Only updates embeds when significant changes occur
- **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
- **Persistent Storage**: Remembers embeds and recreates them between bot restarts
- **Comprehensive Logging**: Detailed logs for all operations and errors
### 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 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
### Prerequisites
- Python 3.8 or higher
- Python 3.8 or higher **or** Docker
- Discord bot token with proper permissions
- 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:
```bash
@@ -50,16 +80,66 @@ A comprehensive Discord bot for managing Pterodactyl game servers through Discor
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:
```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
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
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
[Pterodactyl]
@@ -72,31 +152,29 @@ Token = your.discord.bot.token
AllowedGuildID = 123456789012345678
```
### Configuration Details
- **PanelURL**: Your Pterodactyl panel URL (must include http:// or https://)
- **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
To generate the config file from environment variables:
```bash
python generate_config.py
```
## Usage
Once configured and running, the bot will:
### First Run Setup
1. Connect to your Discord server
2. Sync slash commands
3. Begin monitoring your Pterodactyl servers
4. Update status embeds whenever server status changes or CPU usage spikes up/down for more than 10 seconds
5. Create power control buttons for each Pterodactyl server monitored
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
### 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).
**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
```
### `/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.
## Embed System
### Embed System
The bot uses persistent interactive embeds with the following features:
- **Dynamic Color Coding**: Running (blue) vs offline (red)
- **Resource Monitoring**: CPU, memory, disk, and network usage
- **Interactive Buttons**:
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)
@@ -130,60 +211,94 @@ The bot implements two levels of access control:
Administrators can use the `/refresh_embeds` command.
## Logging
## 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 include:
- DEBUG: Detailed operational information
- INFO: General operational messages
- WARNING: Potential issues
- ERROR: Operational failures
- CRITICAL: Critical failures
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
1. **Embeds not updating**:
- Check bot has proper permissions in the channel
- Verify API keys are correct and have proper permissions
- Use `/refresh_embeds` to reset all embeds
**Embeds not updating:**
- Verify the bot has proper channel permissions
- Check API keys have correct permissions
- Use `/refresh_embeds` to reset all embeds
2. **Buttons not working**:
- Ensure users have the "Game Server User" role
- Verify the bot has proper permissions (View Channel, Send Messages, Embed Links)
**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
3. **API errors**:
- Check your Pterodactyl panel URL and API keys
- Verify the server exists in Pterodactyl
**API errors:**
- Double-check your Pterodactyl panel URL
- Verify API keys are correct and not expired
- Confirm the server exists in Pterodactyl
### Checking Logs
Always check the log files first when troubleshooting:
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
3. Submit a pull request
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
### Development Setup
1. Install development dependencies:
```bash
pip install -r requirements-dev.txt
```
2. Enable debug logging by modifying the logger configuration in the bot code.
### 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
@@ -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.