diff --git a/Usage.md b/Usage.md index e69de29..72946a0 100644 --- a/Usage.md +++ b/Usage.md @@ -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 \ No newline at end of file