diff --git a/Configuration.md b/Configuration.md index e69de29..a5214b1 100644 --- a/Configuration.md +++ b/Configuration.md @@ -0,0 +1,271 @@ +# Configuration + +## Overview + +Pterodisbot supports two configuration methods: +1. **config.ini file** - Traditional file-based configuration +2. **Environment variables** - For Docker/container deployments + +Both methods are validated at startup for required fields and correct formats. + +--- + +## Environment Variables + +When using Docker or generating the config automatically, these environment variables are required: + +| Variable | Description | Example | +|----------|-------------|---------| +| `DISCORD_TOKEN` | Your Discord bot token from Developer Portal | `MTIzNDU2Nzg5...` | +| `ALLOWED_GUILD_ID` | The Discord server ID where the bot operates | `123456789012345678` | +| `PANEL_URL` | Your Pterodactyl panel URL (must include protocol) | `https://panel.example.com` | +| `CLIENT_API_KEY` | Pterodactyl client API key (starts with `ptlc_` or `pacc_`) | `ptlc_abcdef123456...` | +| `APPLICATION_API_KEY` | Pterodactyl application API key (starts with `ptla_` or `papp_`) | `ptla_ghijkl789012...` | + +--- + +## 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 +``` + +### Pterodactyl Section + +| Key | Required | Description | Validation | +|-----|----------|-------------|------------| +| `PanelURL` | ✅ | Panel URL with protocol | Must start with `http://` or `https://` | +| `ClientAPIKey` | ✅ | Client API key for server operations | Must start with `ptlc_` (Pterodactyl) or `pacc_` (Pelican) | +| `ApplicationAPIKey` | ✅ | Application API key for admin operations | Must start with `ptla_` (Pterodactyl) or `papp_` (Pelican) | + +### Discord Section + +| Key | Required | Description | Validation | +|-----|----------|-------------|------------| +| `Token` | ✅ | Discord bot token | Non-empty string | +| `AllowedGuildID` | ✅ | Discord server ID | Positive integer | + +--- + +## Generating Config from Environment Variables + +To generate the config file from environment variables: + +```bash +python generate_config.py +``` + +This reads the environment variables and writes a `config.ini` file. Useful for Docker deployments where you want to mount a config file generated at container startup. + +### Docker Entry Point + +The `entrypoint.sh` script automatically generates config from env vars: + +```bash +#!/bin/sh +python generate_config.py +exec python main.py +``` + +--- + +## Configuration Validation + +The bot performs comprehensive validation at startup: + +### 1. Required Sections Check +- `[Pterodactyl]` section must exist +- `[Discord]` section must exist + +### 2. Required Keys Check +All keys listed above must be present and non-empty. + +### 3. Format Validation + +| Field | Validation Rule | +|-------|----------------| +| `AllowedGuildID` | Must be a positive integer | +| `PanelURL` | Must start with `http://` or `https://` | +| `ClientAPIKey` | Must start with `ptlc_` or `pacc_` | +| `ApplicationAPIKey` | Must start with `ptla_` or `papp_` | + +### 4. Panel Type Detection + +The bot auto-detects panel type from API key prefixes: +- **Pterodactyl**: `ptlc_` / `ptla_` (standard) +- **Pelican Panel**: `pacc_` / `papp_` (fork) + +Access via `Config.is_pelican_panel` property. + +--- + +## Sample Configurations + +### Pterodactyl Panel (Standard) + +```ini +[Pterodactyl] +PanelURL = https://panel.example.com +ClientAPIKey = ptlc_abcdefghijklmnopqrstuvwxyz123456 +ApplicationAPIKey = ptla_zyxwvutsrqponmlkjihgfedcba987654 + +[Discord] +Token = MTIzNDU2Nzg5MDEyMzQ1Njc4.YzA5YzE.YzA5YzEtYzA5YzE +AllowedGuildID = 123456789012345678 +``` + +### Pelican Panel + +```ini +[Pterodactyl] +PanelURL = https://pelican.example.com +ClientAPIKey = pacc_abcdefghijklmnopqrstuvwxyz123456 +ApplicationAPIKey = papp_zyxwvutsrqponmlkjihgfedcba987654 + +[Discord] +Token = MTIzNDU2Nzg5MDEyMzQ1Njc4.YzA5YzE.YzA5YzEtYzA5YzE +AllowedGuildID = 123456789012345678 +``` + +### Docker Environment File (`.env`) + +```bash +# Discord +DISCORD_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4.YzA5YzE.YzA5YzEtYzA5YzE +ALLOWED_GUILD_ID=123456789012345678 + +# Pterodactyl Panel +PANEL_URL=https://panel.example.com +CLIENT_API_KEY=ptlc_abcdefghijklmnopqrstuvwxyz123456 +APPLICATION_API_KEY=ptla_zyxwvutsrqponmlkjihgfedcba987654 +``` + +--- + +## Advanced Configuration + +### Embed Storage Path + +Default: `./embed/embed_locations.json` + +Can be customized by modifying the `Config` class in `config.py`: +```python +self.embed_storage_path: Path = Path("./embed/embed_locations.json") +``` + +### Update Interval + +Default: 10 seconds + +Controlled by the background task decorator in `bot.py`: +```python +@tasks.loop(seconds=10) # UPDATE_INTERVAL = 10 +async def update_status(self) -> None: +``` + +### Required Role + +Default: `Game Server User` + +Hardcoded in `Config` class: +```python +self.required_role: str = "Game Server User" +``` + +To change, modify the source code or create a custom config option. + +### Log Configuration + +Controlled in `logging_config.py`: +- **File**: `logs/pterodisbot.log` +- **Max Size**: 5MB +- **Backups**: 3 files +- **File Level**: DEBUG +- **Console Level**: INFO + +--- + +## Kubernetes Secrets + +For Kubernetes deployments, create a secret with all required values: + +```bash +kubectl create secret generic pterodisbot-config \ + --from-literal=DISCORD_TOKEN='your-discord-bot-token' \ + --from-literal=ALLOWED_GUILD_ID='your-discord-guild-id' \ + --from-literal=PANEL_URL='https://your.pterodactyl.panel' \ + --from-literal=CLIENT_API_KEY='ptlc_your-client-api-key' \ + --from-literal=APPLICATION_API_KEY='ptla_your-application-api-key' \ + -n pterodisbot +``` + +Then reference in deployment: +```yaml +envFrom: + - secretRef: + name: pterodisbot-config +``` + +--- + +## Troubleshooting Configuration + +### Common Validation Errors + +| Error | Cause | Solution | +|-------|-------|----------| +| `Configuration file not found` | Missing `config.ini` | Create file or run `python generate_config.py` | +| `Missing [Pterodactyl] section` | Section header missing | Add `[Pterodactyl]` to config.ini | +| `PanelURL must start with http:// or https://` | Missing protocol | Add `https://` to panel URL | +| `ClientAPIKey should start with 'ptlc_'` | Wrong key prefix | Use correct client API key from panel | +| `AllowedGuildID must be a valid integer` | Non-numeric guild ID | Copy guild ID from Discord (right-click server → Copy ID) | + +### Testing Configuration + +Validate config without starting bot: +```bash +python -c "from config import load_config; load_config('config.ini'); print('Config valid!')" +``` + +### View Current Configuration + +```bash +python -c " +from config import load_config +config = load_config('config.ini') +print(f'Panel: {config.get_panel_display_name()}') +print(f'Panel URL: {config.pterodactyl_url}') +print(f'Guild ID: {config.allowed_guild_id}') +print(f'Required Role: {config.required_role}') +" +``` + +--- + +## Security Best Practices + +1. **Never commit `config.ini` to version control** - Add to `.gitignore` +2. **Use environment variables in production** - Especially for Docker/K8s +3. **Rotate API keys periodically** - Regenerate in panel if compromised +4. **Use HTTPS for panel URL** - Never use `http://` in production +5. **Restrict Discord bot permissions** - Only grant required permissions +6. **Limit "Game Server User" role** - Only assign to trusted users + +--- + +## Related Pages + +- [Architecture](/Architecture) - System design +- [Installation](/Installation) - Deployment guides +- [Usage](/Usage) - Commands and workflows +- [Features](/Features) - Feature details +- [Contributing](/Contributing) - Development guidelines \ No newline at end of file