commit, am too tired to add docs here
This commit is contained in:
371
MIGRATION.md
Normal file
371
MIGRATION.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# GuardDen Migration Guide: Discord Commands to File-Based Configuration
|
||||
|
||||
This guide explains how to migrate from Discord command-based configuration to the new file-based YAML configuration system.
|
||||
|
||||
## Why Migrate?
|
||||
|
||||
The new file-based configuration system offers several advantages:
|
||||
|
||||
- **✅ Version Control**: Track configuration changes with Git
|
||||
- **✅ No Discord Dependencies**: Configure without being in Discord
|
||||
- **✅ Backup & Restore**: Easy configuration backups and restoration
|
||||
- **✅ Hot-Reloading**: Changes apply without bot restarts
|
||||
- **✅ Better Organization**: Clean, structured configuration files
|
||||
- **✅ Schema Validation**: Automatic error checking and prevention
|
||||
- **✅ Bulk Operations**: Configure multiple servers efficiently
|
||||
|
||||
## Migration Overview
|
||||
|
||||
### Phase 1: Preparation
|
||||
1. ✅ Update GuardDen to the latest version
|
||||
2. ✅ Install new dependencies: `pip install -e ".[dev,ai]"`
|
||||
3. ✅ Backup your current configuration (optional but recommended)
|
||||
|
||||
### Phase 2: Export Existing Settings
|
||||
4. ✅ Run the migration tool to export Discord settings to files
|
||||
5. ✅ Verify migration results
|
||||
6. ✅ Review and customize exported configurations
|
||||
|
||||
### Phase 3: Switch to File-Based Configuration
|
||||
7. ✅ Test the new configuration system
|
||||
8. ✅ (Optional) Clean up database configurations
|
||||
|
||||
## Step-by-Step Migration
|
||||
|
||||
### Step 1: Update Dependencies
|
||||
|
||||
```bash
|
||||
# Install new required packages
|
||||
pip install -e ".[dev,ai]"
|
||||
|
||||
# Or if you prefer individual packages:
|
||||
pip install pyyaml jsonschema watchfiles
|
||||
```
|
||||
|
||||
### Step 2: Run Migration Tool
|
||||
|
||||
Export your existing Discord command settings to YAML files:
|
||||
|
||||
```bash
|
||||
# Export all guild configurations from database to files
|
||||
python -m guardden.cli.config migrate from-database
|
||||
|
||||
# This will create files like:
|
||||
# config/guilds/guild-123456789.yml
|
||||
# config/guilds/guild-987654321.yml
|
||||
# etc.
|
||||
```
|
||||
|
||||
**Migration Output Example:**
|
||||
```
|
||||
🔄 Starting migration from database to files...
|
||||
📦 Existing files will be backed up
|
||||
|
||||
📊 Migration Results:
|
||||
✅ Migrated: 3 guilds
|
||||
❌ Failed: 0 guilds
|
||||
⏭️ Skipped: 0 guilds
|
||||
📝 Banned words migrated: 45
|
||||
|
||||
✅ Successfully migrated guilds:
|
||||
• 123456789: My Gaming Server (12 banned words)
|
||||
• 987654321: Friends Chat (8 banned words)
|
||||
• 555666777: Test Server (0 banned words)
|
||||
```
|
||||
|
||||
### Step 3: Verify Migration
|
||||
|
||||
Check that the migration was successful:
|
||||
|
||||
```bash
|
||||
# Verify all guilds
|
||||
python -m guardden.cli.config migrate verify
|
||||
|
||||
# Or verify specific guilds
|
||||
python -m guardden.cli.config migrate verify 123456789 987654321
|
||||
```
|
||||
|
||||
### Step 4: Review Generated Configurations
|
||||
|
||||
Examine the generated configuration files:
|
||||
|
||||
```bash
|
||||
# List all configurations
|
||||
python -m guardden.cli.config guild list
|
||||
|
||||
# Validate configurations
|
||||
python -m guardden.cli.config guild validate
|
||||
```
|
||||
|
||||
**Example Generated Configuration:**
|
||||
```yaml
|
||||
# config/guilds/guild-123456789.yml
|
||||
guild_id: 123456789
|
||||
name: "My Gaming Server"
|
||||
owner_id: 987654321
|
||||
premium: false
|
||||
|
||||
settings:
|
||||
general:
|
||||
prefix: "!"
|
||||
locale: "en"
|
||||
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 80
|
||||
nsfw_only_filtering: false # ← Your new NSFW-only feature!
|
||||
confidence_threshold: 0.7
|
||||
|
||||
automod:
|
||||
message_rate_limit: 5
|
||||
scam_allowlist:
|
||||
- "discord.com"
|
||||
- "github.com"
|
||||
|
||||
# Migrated banned words (if any)
|
||||
banned_words:
|
||||
- pattern: "spam"
|
||||
action: delete
|
||||
is_regex: false
|
||||
reason: "Anti-spam filter"
|
||||
```
|
||||
|
||||
### Step 5: Customize Your Configuration
|
||||
|
||||
Now you can edit the YAML files directly or use the CLI:
|
||||
|
||||
```bash
|
||||
# Enable NSFW-only filtering (only block sexual content)
|
||||
python -m guardden.cli.config guild edit 123456789 ai_moderation.nsfw_only_filtering true
|
||||
|
||||
# Adjust AI sensitivity
|
||||
python -m guardden.cli.config guild edit 123456789 ai_moderation.sensitivity 75
|
||||
|
||||
# Validate changes
|
||||
python -m guardden.cli.config guild validate 123456789
|
||||
```
|
||||
|
||||
**Or edit files directly:**
|
||||
```yaml
|
||||
# Edit config/guilds/guild-123456789.yml
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 75 # Changed from 80
|
||||
nsfw_only_filtering: true # Changed from false
|
||||
confidence_threshold: 0.7
|
||||
```
|
||||
|
||||
### Step 6: Test the New System
|
||||
|
||||
1. **Restart GuardDen** to load the file-based configuration:
|
||||
```bash
|
||||
python -m guardden
|
||||
```
|
||||
|
||||
2. **Test hot-reloading** by editing a config file:
|
||||
```bash
|
||||
# Edit a setting in config/guilds/guild-123456789.yml
|
||||
# Changes should apply within seconds (check bot logs)
|
||||
```
|
||||
|
||||
3. **Verify settings in Discord** using read-only commands:
|
||||
```
|
||||
!config # View current settings
|
||||
!ai # View AI moderation settings
|
||||
!automod # View automod settings
|
||||
```
|
||||
|
||||
### Step 7: Manage Wordlists (Optional)
|
||||
|
||||
Review and customize wordlist configurations:
|
||||
|
||||
```bash
|
||||
# View wordlist status
|
||||
python -m guardden.cli.config wordlist info
|
||||
|
||||
# Edit wordlists directly:
|
||||
nano config/wordlists/banned-words.yml
|
||||
nano config/wordlists/domain-allowlists.yml
|
||||
nano config/wordlists/external-sources.yml
|
||||
```
|
||||
|
||||
## Post-Migration Tasks
|
||||
|
||||
### Backup Your Configuration
|
||||
|
||||
```bash
|
||||
# Create backups of specific guilds
|
||||
python -m guardden.cli.config guild backup 123456789
|
||||
|
||||
# Or backup the entire config directory
|
||||
cp -r config config-backup-$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
### Version Control Setup
|
||||
|
||||
Add configuration to Git for version tracking:
|
||||
|
||||
```bash
|
||||
# Initialize Git repository (if not already)
|
||||
git init
|
||||
git add config/
|
||||
git commit -m "Add GuardDen file-based configuration"
|
||||
|
||||
# Create .gitignore to exclude backups
|
||||
echo "config/backups/" >> .gitignore
|
||||
```
|
||||
|
||||
### Clean Up Database (Optional)
|
||||
|
||||
**⚠️ WARNING: Only do this AFTER verifying migration is successful!**
|
||||
|
||||
```bash
|
||||
# This permanently deletes old configuration from database
|
||||
python -c "
|
||||
import asyncio
|
||||
from guardden.services.config_migration import ConfigurationMigrator
|
||||
from guardden.services.database import Database
|
||||
from guardden.services.guild_config import GuildConfigService
|
||||
from guardden.services.file_config import FileConfigurationManager
|
||||
|
||||
async def cleanup():
|
||||
db = Database('your-db-url')
|
||||
guild_service = GuildConfigService(db)
|
||||
file_manager = FileConfigurationManager()
|
||||
migrator = ConfigurationMigrator(db, guild_service, file_manager)
|
||||
|
||||
# ⚠️ This deletes all guild settings from database
|
||||
results = await migrator.cleanup_database_configs(confirm=True)
|
||||
print(f'Cleaned up: {results}')
|
||||
await db.close()
|
||||
|
||||
asyncio.run(cleanup())
|
||||
"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. Migration Failed for Some Guilds**
|
||||
```bash
|
||||
# Check the specific error messages
|
||||
python -m guardden.cli.config migrate from-database
|
||||
|
||||
# Try migrating individual guilds if needed
|
||||
# (This may require manual file creation)
|
||||
```
|
||||
|
||||
**2. Configuration Validation Errors**
|
||||
```bash
|
||||
# Validate and see specific errors
|
||||
python -m guardden.cli.config guild validate
|
||||
|
||||
# Common fixes:
|
||||
# - Check YAML syntax (indentation, colons, quotes)
|
||||
# - Verify Discord IDs are numbers, not strings
|
||||
# - Ensure boolean values are true/false, not True/False
|
||||
```
|
||||
|
||||
**3. Hot-Reload Not Working**
|
||||
- Check bot logs for configuration errors
|
||||
- Ensure YAML syntax is correct
|
||||
- Verify file permissions are readable
|
||||
- Restart bot if needed: `python -m guardden`
|
||||
|
||||
**4. Lost Configuration During Migration**
|
||||
- Check `config/backups/` directory for backup files
|
||||
- Database configurations are preserved during migration
|
||||
- Re-run migration if needed: `python -m guardden.cli.config migrate from-database`
|
||||
|
||||
### Getting Help
|
||||
|
||||
**View CLI Help:**
|
||||
```bash
|
||||
python -m guardden.cli.config --help
|
||||
python -m guardden.cli.config guild --help
|
||||
python -m guardden.cli.config migrate --help
|
||||
```
|
||||
|
||||
**Check Configuration Status:**
|
||||
```bash
|
||||
python -m guardden.cli.config guild list
|
||||
python -m guardden.cli.config guild validate
|
||||
python -m guardden.cli.config wordlist info
|
||||
```
|
||||
|
||||
**Backup and Recovery:**
|
||||
```bash
|
||||
# Create backup before making changes
|
||||
python -m guardden.cli.config guild backup <guild_id>
|
||||
|
||||
# Recovery from backup (manual file copy)
|
||||
cp config/backups/guild-123456789_20260124_123456.yml config/guilds/guild-123456789.yml
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### NSFW-Only Filtering Setup
|
||||
|
||||
For gaming communities that want to allow violence but block sexual content:
|
||||
|
||||
```yaml
|
||||
# config/guilds/guild-123456789.yml
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 80
|
||||
nsfw_only_filtering: true # Only block sexual content
|
||||
confidence_threshold: 0.7
|
||||
nsfw_detection_enabled: true
|
||||
log_only: false
|
||||
```
|
||||
|
||||
### High-Security Server Setup
|
||||
|
||||
For family-friendly or professional servers:
|
||||
|
||||
```yaml
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 95 # Very strict
|
||||
nsfw_only_filtering: false # Block all inappropriate content
|
||||
confidence_threshold: 0.6 # Lower threshold = more sensitive
|
||||
log_only: false
|
||||
|
||||
automod:
|
||||
message_rate_limit: 3 # Stricter rate limiting
|
||||
message_rate_window: 5
|
||||
duplicate_threshold: 2 # Less tolerance for duplicates
|
||||
```
|
||||
|
||||
### Development/Testing Server Setup
|
||||
|
||||
For development or testing environments:
|
||||
|
||||
```yaml
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 50 # More lenient
|
||||
nsfw_only_filtering: false
|
||||
confidence_threshold: 0.8 # Higher threshold = less sensitive
|
||||
log_only: true # Only log, don't take action
|
||||
|
||||
automod:
|
||||
message_rate_limit: 10 # More relaxed limits
|
||||
message_rate_window: 5
|
||||
```
|
||||
|
||||
## Benefits of File-Based Configuration
|
||||
|
||||
After migration, you'll enjoy:
|
||||
|
||||
1. **Easy Bulk Changes**: Edit multiple server configs at once
|
||||
2. **Configuration as Code**: Version control your bot settings
|
||||
3. **Environment Management**: Different configs for dev/staging/prod
|
||||
4. **Disaster Recovery**: Easy backup and restore of all settings
|
||||
5. **No Discord Dependency**: Configure servers before bot joins
|
||||
6. **Better Organization**: All settings in structured, documented files
|
||||
7. **Hot-Reloading**: Changes apply instantly without restarts
|
||||
8. **Schema Validation**: Automatic error checking prevents misconfigurations
|
||||
|
||||
**Welcome to the new GuardDen configuration system! 🎉**
|
||||
Reference in New Issue
Block a user