Petbot/QUICKSTART.md

PetBot Quick Start Guide

Prerequisites Installation

Method 1: Automatic Installation (Recommended)

Run the automatic installation script:

# Make the script executable
chmod +x install_prerequisites.sh

# Run the installation
./install_prerequisites.sh

Or use the Python version:

python3 install_prerequisites.py

Method 2: Manual Installation

If you prefer manual installation:

# Install required packages
pip3 install -r requirements.txt

# Or install individually
pip3 install irc>=20.3.0 aiosqlite>=0.19.0 python-dotenv>=1.0.0

# Create required directories
mkdir -p data backups logs

System Requirements

• Python: 3.7 or higher
• pip: Python package installer
• Operating System: Linux, macOS, or Windows with Python support

Quick Start

1. Install Prerequisites

./install_prerequisites.sh

2. Test Basic Functionality

# Test backup system
python3 test_backup_simple.py

# Test IRC reconnection system
python3 test_reconnection.py

3. Run the Bot

Option A: Debug Mode (Original)

python3 run_bot_debug.py

Option B: With Auto-Reconnect (Recommended)

python3 run_bot_with_reconnect.py

4. Access Web Interface

Open your browser and go to:

• Local: http://localhost:8080
• Production: http://petz.rdx4.com (if configured)

Configuration

IRC Settings

Edit the configuration in the bot files:

config = {
    "server": "irc.libera.chat",
    "port": 6667,
    "nickname": "PetBot",
    "channel": "#petz",
    "command_prefix": "!"
}

Database

The bot uses SQLite database stored in data/petbot.db. No additional setup required.

Available Commands

Basic Commands

• !help - Show available commands
• !start - Begin your pet journey
• !stats - View your stats
• !pets - View your pets

Connection Monitoring

• !status - Show bot connection status
• !uptime - Show bot uptime
• !ping - Test bot responsiveness

Admin Commands

• !backup - Create database backup
• !restore <filename> - Restore database
• !reload - Reload bot modules
• !reconnect - Force IRC reconnection

Troubleshooting

Common Issues

1. ModuleNotFoundError: Run the prerequisites installer
2. Permission Denied: Make sure scripts are executable (chmod +x)
3. Database Errors: Check that data/ directory exists and is writable
4. IRC Connection Issues: Check network connectivity and IRC server status

Getting Help

1. Check the error logs in console output
2. Review CLAUDE.md for development guidelines
3. Check issues.txt for known security issues
4. Review TODO.md for current project status

Log Files

Logs are displayed in the console. For persistent logging, redirect output:

python3 run_bot_with_reconnect.py > logs/bot.log 2>&1

Development

Running Tests

# Test backup system
python3 test_backup_simple.py

# Test reconnection system
python3 test_reconnection.py

Code Structure

PetBot/
├── src/                    # Core system
│   ├── database.py        # Database operations
│   ├── game_engine.py     # Game logic
│   ├── bot.py            # IRC bot core
│   ├── irc_connection_manager.py  # Connection handling
│   └── backup_manager.py  # Backup system
├── modules/               # Command modules
├── config/               # Configuration files
├── webserver.py          # Web interface
└── run_bot_*.py          # Bot runners

Adding New Commands

1. Create a new method in appropriate module
2. Add command to get_commands() list
3. Test thoroughly
4. Update documentation

Security

⚠️ Important: Review issues.txt for security vulnerabilities before production deployment.

Key security considerations:

• Run behind HTTPS reverse proxy
• Review XSS vulnerabilities in web interface
• Implement proper authentication
• Keep dependencies updated

Next Steps

1. ✅ Run prerequisites installer
2. ✅ Test basic functionality
3. ✅ Start the bot
4. ✅ Access web interface
5. 📋 Review security issues
6. 🔧 Configure for production
7. 🚀 Deploy and monitor

Support

For issues or questions:

1. Check this guide and documentation
2. Review error messages and logs
3. Test with the provided test scripts
4. Check network connectivity and dependencies

Happy bot hosting! 🐾