Update "Usage"

2026-10-26 12:10:23 +00:00
1 parent 55d25fb3ed
commit b2c775d992
@@ -0,0 +1,350 @@
+# Usage
+
+## Overview
+
+This page documents how to use Pterodisbot after installation, including first-run setup, commands, and the embed system.
+
+---
+
+## First Run Setup
+
+1. **Ensure bot is invited** to your Discord server with proper permissions (see [Discord Bot Setup](/Installation#discord-bot-setup))
+
+2. **Verify "Game Server User" role** exists in your server with exact name match
+
+3. **Start the bot** using your preferred installation method:
+   ```bash
+   # Traditional
+   python main.py
+   
+   # Docker
+   docker-compose up -d
+   
+   # Kubernetes
+   kubectl apply -f deployment.yaml
+   ```
+
+4. **Bot should appear online** in your server
+
+5. **Use `/server_status`** to create your first status embed
+
+---
+
+## Bot Commands
+
+### `/server_status`
+
+Display an interactive dropdown menu containing all available servers from your Pterodactyl panel. Select a server to create a permanent status embed in the current channel with real-time monitoring and control buttons.
+
+**Features:**
+- Shows total server count and online/offline statistics
+- Lists all servers with descriptions
+- Creates persistent, auto-updating embeds
+- Automatically removes old embeds when recreating for the same server
+
+**Usage:**
+1. Type `/server_status` in any channel where the bot has permissions
+2. Select a server from the dropdown menu (ephemeral - only you see it)
+3. The server's status embed is posted in the current channel
+4. Anyone with the "Game Server User" role can interact with the embed
+
+**Example Output:**
+```
+🏗️ Server Status Dashboard
+Select a server from the dropdown below to view its detailed status and controls.
+
+📊 Server Statistics
+Total Servers: 5
+✅ Online: 3
+❌ Offline: 2
+
+ℹ️ How to Use
+Use the dropdown menu below to select a server. The server's status embed will be posted in this channel.
+
+[Dropdown: Select a server to display... ▼]
+```
+
+### `/refresh_embeds` (Admin Only)
+
+Force a complete refresh of all server status embeds. Requires **Administrator** permission.
+
+**What it does:**
+- Recreates all tracked embeds with fresh data
+- Deletes old embed messages to prevent duplication
+- Updates embed tracking storage
+- Provides statistics on deleted and created embeds
+
+**Use Cases:**
+- Embeds appear out of sync with actual server states
+- After bot configuration changes
+- Following Discord API issues
+
+**Example Output:**
+```
+Refreshed all embeds. Deleted 5 old embeds, created 5 new ones.
+```
+
+### `/purge_embeds` (Admin Only)
+
+Permanently delete all server status embeds from the Discord server. Requires **Administrator** permission.
+
+**What it does:**
+- Removes all tracked embed messages
+- Clears the embed tracking file
+- Provides real-time progress updates
+- Shows detailed statistics (deleted, missing, errors)
+
+**Use Cases:**
+- Starting fresh with new embed layout
+- Removing bot from server
+- Cleaning up after testing
+
+**Example Progress:**
+```
+🔄 Purging Server Embeds
+Processing 5 embeds...
+Deleted: 2 | Not Found: 1 | Errors: 0
+```
+
+**Example Result:**
+```
+✅ Embed Purge Complete
+Total Tracked: 5
+✅ Successfully Deleted: 3
+❌ Already Missing: 1
+⚠️ Errors: 1
+📊 Success Rate: 80.0%
+Embed tracking file has been cleared
+```
+
+---
+
+## Embed System
+
+Status embeds dynamically display comprehensive server information with interactive controls.
+
+### Header Information
+- **Server name** with current state (color-coded)
+- **Server description** from Pterodactyl panel
+- **Last updated timestamp** (auto-updates)
+
+### Status Fields
+| Field | Description |
+|-------|-------------|
+| 🆔 **Server ID** | Pterodactyl identifier (backtick formatted) |
+| ℹ️ **Status** | Active ✅ or Suspended ⛔ |
+| ⏱️ **Uptime** | Human-readable (for running servers) |
+
+### Resource Usage (When Online)
+
+Formatted as a properties-style code block:
+```
+properties
+CPU    : [   15.50 /     100 %]
+Memory : [  1024.00 /    4096 MiB]
+Disk   : [  5120.00 /   20480 MiB]
+```
+
+Additional network fields:
+- **Network In** 📥: Incoming traffic (MiB)
+- **Network Out** 📤: Outgoing traffic (MiB)
+
+### Metrics Visualization (When Running)
+
+**Combined CPU and Memory Graph** showing last 1 minute:
+- 6 data points at 10-second intervals
+- Discord dark theme optimized
+- Dynamic CPU scaling (100% increments for multi-vCPU)
+- Trend indicators (increasing/decreasing/stable)
+- Data point counter (X/6)
+
+**Graph Fields:**
+```
+📈 Usage Trends (Last Minute)
+>>> `Data points: 4/6`
+`CPU trend: stable • Memory trend: increasing`
+```
+[Graph image attached]
+
+### Interactive Buttons
+
+| Button | Style | Action | Permission Required |
+|--------|-------|--------|---------------------|
+| **Start** | 🟢 Green | Powers on the server | Game Server User |
+| **Stop** | 🔴 Red | Gracefully shuts down | Game Server User |
+| **Restart** | 🔵 Blurple | Reboots the server | Game Server User |
+| **Show Address** | ⚪ Grey | Displays IP:Port | Game Server User |
+
+**Button Responses** (ephemeral - private to user):
+- Success: "Server 'Name' is starting..."
+- Error: "Failed to start server: [API error message]"
+
+### Automatic Updates
+
+Embeds refresh when server state changes:
+- Power state transitions (offline ↔ starting ↔ running)
+- Significant resource usage changes (CPU >50% shift)
+- Periodic updates for uptime accuracy (every 10 minutes for running servers)
+- Rate limit protection with built-in delays
+
+### Embed Persistence
+
+- Locations stored in `embed/embed_locations.json`
+- Survives bot restarts and crashes
+- Format:
+```json
+{
+  "server_identifier": {
+    "channel_id": "123456789012345678",
+    "message_id": "987654321098765432"
+  }
+}
+```
+
+---
+
+## Permissions
+
+### 1. Guild Restriction
+The bot only responds to commands and interactions from the Discord server specified in `AllowedGuildID`. This prevents unauthorized use if the bot is accidentally added to other servers.
+
+### 2. Role-Based Access
+Users must have the **"Game Server User"** role (exact name match) to:
+- Use server control buttons (Start/Stop/Restart)
+- View server addresses
+- Interact with any bot features
+
+### 3. Administrator Access
+Server administrators (users with Discord's Administrator permission) can additionally:
+- Use `/refresh_embeds` command
+- Use `/purge_embeds` command
+- No special role required - based on Discord permissions
+
+**Note:** The `/server_status` command can be used by anyone, but only users with the "Game Server User" role can interact with the resulting embeds.
+
+---
+
+## Logging System
+
+### File Logs
+- **Location**: `logs/pterodisbot.log`
+- **Rotation**: Automatic rotation when file reaches 5MB
+- **Backups**: Keeps 3 previous log files (`pterodisbot.log.1`, `.2`, `.3`)
+- **Format**: `YYYY-MM-DD HH:MM:SS - LEVEL - MESSAGE`
+
+### Console Output
+- **Real-time**: Logs appear in stdout/stderr
+- **Format**: Same as file logs
+- **Level**: INFO and above (less verbose than file logs)
+
+### Log Levels
+
+| Level | Description |
+|-------|-------------|
+| **DEBUG** | Detailed operational information (API calls, state changes, cache operations) |
+| **INFO** | General operational messages (bot startup, command usage, successful operations) |
+| **WARNING** | Potential issues (missing embeds, API warnings, permission issues) |
+| **ERROR** | Operational failures (API errors, Discord API issues, failed operations) |
+| **CRITICAL** | Critical failures (configuration errors, startup failures, unrecoverable errors) |
+
+### Example Log Entries
+
+```
+2025-09-29 03:51:13,743 - INFO - Initialized logging system with file and console output
+2025-09-29 03:51:16,828 - INFO - Starting full refresh of all server embeds
+2025-09-29 03:51:16,829 - INFO - Bot connected as Petrodisbot (ID: 1419694924458360964)
+2025-09-29 03:52:10,481 - INFO - Start button pressed for Minecraft Server by username
+2025-09-29 03:52:14,406 - DEBUG - Power state changed for Minecraft Server: offline -> starting
+```
+
+### Checking Logs
+
+**Real-time monitoring:**
+```bash
+# Traditional installation
+tail -f logs/pterodisbot.log
+
+# Docker installation
+docker logs -f pterodisbot
+
+# Docker Compose
+docker-compose logs -f pterodisbot
+
+# Kubernetes
+kubectl logs -n pterodisbot -l app=pterodisbot -f
+```
+
+**Searching logs:**
+```bash
+# Find all ERROR level messages
+grep "ERROR" logs/pterodisbot.log
+
+# Find logs for specific server
+grep "Server_Name" logs/pterodisbot.log
+
+# View last 100 lines
+tail -n 100 logs/pterodisbot.log
+```
+
+---
+
+## Workflow Examples
+
+### Daily Server Management
+1. User types `/server_status`
+2. Selects "Minecraft Server" from dropdown
+3. Embed appears in channel with current status
+4. User clicks "Start" button → server starts
+5. Embed auto-updates to "Running" with metrics
+6. User clicks "Show Address" → gets IP:Port privately
+
+### Admin Maintenance
+1. Admin notices embeds out of sync
+2. Types `/refresh_embeds`
+3. All embeds recreated with fresh data
+4. Statistics shown: "Deleted 3 old embeds, created 3 new ones"
+
+### Cleanup
+1. Admin wants to remove all bot embeds
+2. Types `/purge_embeds`
+3. Progress embed shows real-time deletion
+4. Final result shows success rate
+5. Embed tracking file cleared
+
+---
+
+## Troubleshooting Common Issues
+
+### Embeds not updating
+- Verify bot has channel permissions (View Channel, Send Messages, Embed Links)
+- Check both API keys are valid
+- Review logs for API errors
+- Use `/refresh_embeds` to force-recreate
+
+### Buttons not working
+- Confirm users have "Game Server User" role (exact name)
+- Verify role assignment
+- Check bot permissions include "Use Slash Commands"
+- Ensure interaction is in correct guild
+
+### Commands not appearing
+- Wait 5-10 minutes after startup (command sync takes time)
+- Verify "Use Slash Commands" permission
+- Check bot is in correct guild
+- Review logs for sync errors
+
+### Graphs not appearing
+- Wait 20+ seconds after server starts (needs 2 data points)
+- Verify server is "running" state
+- Check matplotlib installation
+- Review logs for graph generation errors
+
+---
+
+## Related Pages
+
+- [Architecture](/Architecture) - System design
+- [Installation](/Installation) - Deployment guides
+- [Configuration](/Configuration) - Config options
+- [Features](/Features) - Feature details
+- [Contributing](/Contributing) - Development guidelines