Create README

2025-07-20 00:56:11 -07:00
parent aac9c2c535
commit 88de5b1d99
1 changed files with 192 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,193 @@
-# pterodactyl-discord-bot
+# Pterodactyl Discord Bot

+![Pterodactyl Logo](https://pterodactyl.io/logos/new/pterodactyl_logo.png)
+
+A comprehensive Discord bot for managing Pterodactyl game servers through Discord, providing real-time status monitoring and control capabilities.
+
+## Table of Contents
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Commands](#commands)
+- [Embed System](#embed-system)
+- [Permissions](#permissions)
+- [Logging](#logging)
+- [Troubleshooting](#troubleshooting)
+- [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
+- **Persistent Storage**: Remembers embed locations between bot restarts
+- **Comprehensive Logging**: Detailed logs for all operations and errors
+
+## Installation
+
+### Prerequisites
+- Python 3.8 or higher
+- Discord bot token with proper permissions
+- Pterodactyl panel with API access
+- Server with Client and Application API keys
+
+### Setup Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/pterodactyl-discord-bot.git
+   cd pterodactyl-discord-bot
+   ```
+
+2. Install required dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Create a `config.ini` file (see [Configuration](#configuration) section)
+
+4. Run the bot:
+   ```bash
+   python pterodisbot.py
+   ```
+
+## Configuration
+
+The bot requires a `config.ini` file with the following structure:
+
+```ini
+[Pterodactyl]
+PanelURL = https://your.pterodactyl.panel
+ClientAPIKey = ptlc_yourclientkey
+ApplicationAPIKey = ptla_yourapplicationkey
+
+[Discord]
+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
+
+## Usage
+
+Once configured and running, the bot will:
+
+1. Connect to your Discord server
+2. Sync slash commands
+3. Begin monitoring your Pterodactyl servers
+4. Update status embeds every 10 seconds (configurable)
+
+### First Run
+
+On first run, you'll need to manually create status embeds using the `/server_status` command for each server you want to monitor.
+
+## 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
+
+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**:
+  - 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
+
+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
+
+## 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
+
+2. **Buttons not working**:
+   - Ensure users have the "Game Server User" role
+   - Verify the bot has proper permissions (View Channel, Send Messages, Embed Links)
+
+3. **API errors**:
+   - Check your Pterodactyl panel URL and API keys
+   - Verify the server exists in Pterodactyl
+
+### Checking Logs
+
+Always check the log files first when troubleshooting:
+```bash
+tail -f pterodactyl_bot.log
+```
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+1. Fork the repository
+2. Create a feature branch
+3. Submit 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.
+
+## License
+
+This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**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.