pterodactyl-discord-bot/README.md

# 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)
- [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)
- [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

## 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
```

## 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.