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.

Features
Architecture Overview
Installation
- Traditional Installation
- Docker Installation
Configuration
- Environment Variables
- Configuration File
Usage
Permissions
Logging System
Troubleshooting
Development
Contributing
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:

PterodactylAPI Class: Handles all communication with the Pterodactyl Panel API
ServerStatusView Class: Manages the interactive Discord UI with control buttons
PterodactylBot Class: Main bot class that orchestrates all operations
Background Task: Regularly checks server status and updates embeds when needed
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

Clone the repository:

git clone https://git.serendipity.systems/k.eaven/pterodactyl-discord-bot.git
cd pterodactyl-discord-bot

Install required dependencies:
```
pip install -r requirements.txt
```
Create and configure your config.ini file (see Configuration section)
Run the bot:
```
python pterodisbot.py
```

Docker Installation

Clone the repository:

git clone https://git.serendipity.systems/k.eaven/pterodactyl-discord-bot.git
cd pterodactyl-discord-bot

Build the Docker image:
```
docker build -t pterodisbot .
```
Create a directory for configuration:
```
mkdir -p bot-config
```
Create a config.ini file in the bot-config directory with your settings

Run the container with the config mounted:

docker run -d \
  --name pterodisbot \
  -v $(pwd)/bot-config:/app \
  pterodisbot

For Docker Compose, create a docker-compose.yml file:

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:

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:

[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:

python generate_config.py

Usage

First Run Setup

Invite your bot to your Discord server with these permissions:
- View Channels
- Send Messages
- Embed Links
- Manage Messages (for embed updates)
- Use Slash Commands
Create a "Game Server User" role for users who should control servers
Use the /server_status command to create your first status embed

Bot 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

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:

Guild Restriction: Only works in the Discord server specified in AllowedGuildID
Role Requirement: Users must have the "Game Server User" role to interact with server controls

Administrators can use the /refresh_embeds command.

Logging System

The bot maintains comprehensive logs in two locations:

File Logs: Rotating log files (5MB max, 3 backups) in pterodactyl_bot.log
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:

tail -f pterodactyl_bot.log

Development

Requirements

Python 3.8+
Poetry (recommended) or pip

Setup

Clone the repository

Install dependencies:

poetry install

pip install -r requirements.txt -r requirements-dev.txt

Create a .env file with your development environment variables
Run in development mode:
```
python pterodisbot.py
```

Testing

The project includes unit tests (to be expanded). Run with:

pytest

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin feature/your-feature)
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 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.

README.md

Pterodactyl Discord Bot

Table of Contents