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

Add: README directory
All checks were successful
CI/CD Pipeline / Unit Tests (Python 3.10) (push) Successful in 57s
Details
CI/CD Pipeline / Unit Tests (Python 3.11) (push) Successful in 55s
Details
CI/CD Pipeline / Unit Tests (Python 3.9) (push) Successful in 53s
Details
CI/CD Pipeline / Integration Tests (push) Successful in 17s
Details
CI/CD Pipeline / Security Scanning (push) Successful in 19s
Details
CI/CD Pipeline / Code Quality & Linting (push) Successful in 45s
Details
CI/CD Pipeline / Generate Test Report (push) Successful in 4s
Details
CI/CD Pipeline / Build Docker Image (push) Successful in 10m21s
Details
CI/CD Pipeline / CI/CD Pipeline Status (push) Successful in 3s
Details

Browse Source
This commit is contained in:
Eaven Kimura
2025-11-04 11:54:52 +00:00
parent f80e253401
commit 21208897b0
1 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

324
README/README.md Normal file
View File

@@ -0,0 +1,324 @@
# Pterodactyl Discord Bot
![Pterodactyl X Discord](md_images/Pterodisbot_README_Header.png)
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 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/k.eaven/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. Clone the repository:
```bash
git clone https://git.serendipity.systems/k.eaven/pterodactyl-discord-bot.git
cd pterodactyl-discord-bot
```
2. Build the Docker image:
```bash
docker build -t pterodisbot .
```
3. Create a directory for configuration:
```bash
mkdir -p bot-config
```
4. Create a `config.ini` file in the `bot-config` directory with your settings
5. Run the container with the config mounted:
```bash
docker run -d \
--name pterodisbot \
-v $(pwd)/bot-config:/app \
pterodisbot
```
6. For Docker Compose, create a `docker-compose.yml` file:
```yaml
services:
pterodisbot:
build: .
environment:
# Remmove brackets and spaces in environment variables
# Ideally, use .env file to assign values to these instead
- 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_`)}
volumes:
- bot_logs:/app/logs
- bot_embed:/app/embed
restart: unless-stopped
volumes:
bot_logs:
bot_embed:
```
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`
Display an interactive context menu containing all available servers which can be selected to create an embed for a given server.
#### `/refresh_embeds` (Admin only)
Force a refresh of all server status embeds. This is useful if embeds become out of sync.
#### `/purge_embeds` (Admin only)
Delete all embeds from the Discord guild.
### 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` and `/purge_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.