Update "Configuration"
k.eaven committed
1 parent
625d9e60bd
commit
55d25fb3ed
1 file changed
+271
+271
@@ -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
|
||||||
Reference in new issue
Block a user