Petbot/QUICKSTART.md

# PetBot Quick Start Guide

## Prerequisites Installation

### Method 1: Automatic Installation (Recommended)

Run the automatic installation script:

```bash
# Make the script executable
chmod +x install_prerequisites.sh

# Run the installation
./install_prerequisites.sh
```

Or use the Python version:

```bash
python3 install_prerequisites.py
```

### Method 2: Manual Installation

If you prefer manual installation:

```bash
# 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

```bash
./install_prerequisites.sh
```

### 2. Test Basic Functionality

```bash
# 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)
```bash
python3 run_bot_debug.py
```

#### Option B: With Auto-Reconnect (Recommended)
```bash
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:

```python
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:

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

## Development

### Running Tests

```bash
# 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! 🐾