diff --git a/README.md b/README.md index 7b93d07..f31470e 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file +**Note**: This bot is designed for single Pterodactyl domain and single Discord server use. For multi-instance support, significant modifications would be required. \ No newline at end of file