Petbot/INSTALLATION.md

# PetBot Installation Guide

## Overview

PetBot is a Python-based IRC bot with web interface for Pokemon-style pet collecting. This guide covers complete installation and setup.

## Prerequisites

### System Requirements

- **Python**: 3.7 or higher
- **pip**: Python package installer
- **Operating System**: Linux, macOS, or Windows with Python support
- **Memory**: 512MB RAM minimum
- **Storage**: 1GB available space
- **Network**: Internet connection for IRC and web access

### Required Python Packages

- `irc>=20.3.0` - IRC client library
- `aiosqlite>=0.19.0` - Async SQLite database interface
- `python-dotenv>=1.0.0` - Environment variable loading

## Installation Methods

### Method 1: Automatic Installation (Recommended)

#### Step 1: Download and Run Installation Script

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

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

#### Step 2: Alternative Python Script

If the shell script doesn't work:

```bash
python3 install_prerequisites.py
```

### Method 2: Manual Installation

#### Step 1: Install System Dependencies

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv
```

**CentOS/RHEL:**
```bash
sudo yum install python3 python3-pip
```

**macOS:**
```bash
# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3
```

**Windows:**
1. Download Python from https://python.org/downloads/
2. Run installer and check "Add Python to PATH"
3. Open Command Prompt as administrator

#### Step 2: Install Python Packages

```bash
# Install from requirements file
pip3 install -r requirements.txt

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

#### Step 3: Create Required Directories

```bash
mkdir -p data backups logs
```

#### Step 4: Make Scripts Executable (Linux/macOS)

```bash
chmod +x run_bot_debug.py
chmod +x run_bot_with_reconnect.py
chmod +x test_backup_simple.py
chmod +x test_reconnection.py
```

## Verification

### Test Installation

```bash
# Test backup system
python3 test_backup_simple.py

# Test IRC reconnection system
python3 test_reconnection.py
```

### Expected Output

Both tests should show:
```
🎉 All tests passed! ... is working correctly.
```

## Configuration

### IRC Settings

The bot connects to IRC with default settings:

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

To modify these settings, edit the configuration in:
- `run_bot_debug.py` (line 21-27)
- `run_bot_with_reconnect.py` (line 35-41)

### Database Configuration

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

### Web Server Configuration

The web server runs on port 8080 by default. To change:
- Edit `webserver.py` or bot runner files
- Update the port number in web server initialization

## Running the Bot

### Option 1: Debug Mode (Original)

```bash
python3 run_bot_debug.py
```

**Features:**
- Basic IRC connection
- Console debugging output
- Module loading and validation
- Web server on port 8080

### Option 2: Auto-Reconnect Mode (Recommended)

```bash
python3 run_bot_with_reconnect.py
```

**Features:**
- Automatic IRC reconnection
- Connection health monitoring
- Exponential backoff for reconnection
- Comprehensive logging
- Connection statistics
- Web server on port 8080

### Running as a Service (Linux)

Create a systemd service file:

```bash
sudo nano /etc/systemd/system/petbot.service
```

```ini
[Unit]
Description=PetBot IRC Bot
After=network.target

[Service]
Type=simple
User=petbot
WorkingDirectory=/path/to/petbot
ExecStart=/usr/bin/python3 run_bot_with_reconnect.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl enable petbot
sudo systemctl start petbot
sudo systemctl status petbot
```

## Web Interface

### Access

- **Local**: http://localhost:8080
- **Production**: Configure reverse proxy for HTTPS

### Available Pages

- `/` - Homepage and help
- `/players` - Player leaderboard
- `/player/<name>` - Player profile
- `/teambuilder/<name>` - Team builder with PIN verification

## Troubleshooting

### Common Issues

#### 1. ModuleNotFoundError

**Error:** `ModuleNotFoundError: No module named 'irc'`

**Solution:**
```bash
pip3 install irc>=20.3.0 aiosqlite>=0.19.0 python-dotenv>=1.0.0
```

#### 2. Permission Denied

**Error:** `Permission denied: './install_prerequisites.sh'`

**Solution:**
```bash
chmod +x install_prerequisites.sh
```

#### 3. Database Errors

**Error:** `sqlite3.OperationalError: unable to open database file`

**Solution:**
```bash
mkdir -p data
chmod 755 data
```

#### 4. IRC Connection Issues

**Error:** `Could not connect to irc.libera.chat:6667`

**Solution:**
- Check internet connection
- Verify IRC server is accessible
- Check firewall settings
- Try different IRC server/port

#### 5. Web Interface Not Accessible

**Error:** `Connection refused on port 8080`

**Solution:**
- Check if bot is running
- Verify port 8080 is not blocked
- Check firewall settings
- Try accessing via 127.0.0.1:8080

### Debugging

#### Enable Debug Logging

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

#### Check System Resources

```bash
# Check memory usage
free -h

# Check disk space
df -h

# Check network connectivity
ping irc.libera.chat
```

#### Test Individual Components

```bash
# Test database
python3 -c "from src.database import Database; db = Database(); print('Database OK')"

# Test IRC connection manager
python3 -c "from src.irc_connection_manager import IRCConnectionManager; print('IRC manager OK')"

# Test web server
python3 -c "import webserver; print('Web server OK')"
```

## Security Considerations

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

### Immediate Actions Required

1. **HTTPS**: Run behind reverse proxy with SSL
2. **Authentication**: Implement web interface authentication
3. **Input Validation**: Fix XSS vulnerabilities
4. **Access Control**: Implement proper user authorization

### Production Checklist

- [ ] SSL/TLS certificate installed
- [ ] Reverse proxy configured (nginx/Apache)
- [ ] Firewall rules configured
- [ ] User authentication implemented
- [ ] Input validation added
- [ ] Security headers configured
- [ ] Database backups scheduled
- [ ] Log rotation configured
- [ ] Monitoring alerts set up

## Performance Optimization

### Database

- Enable WAL mode for better concurrent access
- Regular VACUUM operations
- Monitor database size and growth

### Web Server

- Use reverse proxy for static files
- Enable gzip compression
- Implement caching for static content

### IRC Connection

- Monitor connection stability
- Adjust reconnection parameters if needed
- Set up connection monitoring alerts

## Backup and Recovery

### Automated Backups

The bot includes automated backup system:

```bash
# Manual backup
python3 -c "
import asyncio
from src.backup_manager import BackupManager
bm = BackupManager()
result = asyncio.run(bm.create_backup('manual', True))
print(f'Backup created: {result}')
"
```

### Recovery

```bash
# List available backups
ls -la backups/

# Restore from backup (use admin command or direct restore)
python3 -c "
import asyncio
from src.backup_manager import BackupManager
bm = BackupManager()
result = asyncio.run(bm.restore_backup('backup_filename.db.gz'))
print(f'Restore result: {result}')
"
```

## Monitoring

### Connection Health

Use the connection monitoring commands:

```
!status        # Check connection status
!uptime        # Show uptime and stats
!ping          # Test responsiveness
!connection_stats  # Detailed statistics
```

### Log Monitoring

Monitor logs for:
- Connection failures
- Database errors
- Command execution errors
- Security events

### System Resources

Monitor:
- Memory usage
- CPU usage
- Disk space
- Network connectivity

## Development

### Adding New Features

1. Follow patterns in `CLAUDE.md`
2. Create new modules in `modules/`
3. Update documentation
4. Add tests
5. Test thoroughly

### Contributing

1. Review security issues in `issues.txt`
2. Follow coding conventions
3. Add comprehensive tests
4. Update documentation
5. Consider security implications

## Support

### Documentation

- `README.md` - Project overview
- `CLAUDE.md` - Development guidelines
- `TODO.md` - Current project status
- `issues.txt` - Security audit findings
- `BACKUP_SYSTEM_INTEGRATION.md` - Backup system guide

### Getting Help

1. Check error logs and console output
2. Review troubleshooting section
3. Test with provided test scripts
4. Check network connectivity
5. Verify all dependencies are installed

## Next Steps

1. ✅ Complete installation
2. ✅ Test basic functionality
3. ✅ Configure IRC settings
4. ✅ Start the bot
5. ✅ Access web interface
6. 📋 Review security issues
7. 🔧 Configure for production
8. 🚀 Deploy and monitor

Congratulations! Your PetBot should now be running successfully. 🐾