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

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

python3 install_prerequisites.py

Method 2: Manual Installation

Step 1: Install System Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

CentOS/RHEL:

sudo yum install python3 python3-pip

macOS:

# 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

# 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

mkdir -p data backups logs

Step 4: Make Scripts Executable (Linux/macOS)

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

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

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)

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)

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:

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

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

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:

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:

chmod +x install_prerequisites.sh

3. Database Errors

Error: sqlite3.OperationalError: unable to open database file

Solution:

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

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

Check System Resources

# Check memory usage
free -h

# Check disk space
df -h

# Check network connectivity
ping irc.libera.chat

Test Individual Components

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

# 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

# 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. 🐾