Hiddenden/GuardDen
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7612770625016a2f88828bb4c219b200a8cef326
GuardDen/MIGRATION.md

9.7 KiB
Raw Blame History

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

  1. ✅ Run the migration tool to export Discord settings to files
  2. ✅ Verify migration results
  3. ✅ Review and customize exported configurations

Phase 3: Switch to File-Based Configuration

  1. ✅ Test the new configuration system
  2. ✅ (Optional) Clean up database configurations

Step-by-Step Migration

Step 1: Update Dependencies

# 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:

# 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:

# 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:

# List all configurations
python -m guardden.cli.config guild list

# Validate configurations  
python -m guardden.cli.config guild validate

Example Generated Configuration:

# 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:

# 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:

# 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:

    python -m guardden

  2. Test hot-reloading by editing a config file:

    # 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:

# 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

# 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:

# 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!

# 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

# 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

# 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:

python -m guardden.cli.config --help
python -m guardden.cli.config guild --help
python -m guardden.cli.config migrate --help

Check Configuration Status:

python -m guardden.cli.config guild list
python -m guardden.cli.config guild validate
python -m guardden.cli.config wordlist info

Backup and Recovery:

# 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:

# 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:

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:

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 View Git Blame Copy Permalink