discord-fishbowl/INSTALL.md

Discord Fishbowl Installation Guide

Quick Start

Run the interactive setup script to get started:

python install.py

This script will:

• ✅ Check system requirements
• ✅ Create a Python virtual environment
• ✅ Install all dependencies
• ✅ Guide you through configuration
• ✅ Set up the database
• ✅ Create startup scripts

Prerequisites

Required

• Python 3.8+ - The core application
• Git - For version control and updates

Optional (but recommended)

• Node.js & npm - For the admin web interface
• PostgreSQL - For production database (SQLite available for testing)
• Redis - For caching and real-time features
• Qdrant - For vector database and semantic search

Manual Installation

If you prefer manual setup:

1. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate.bat  # Windows

2. Install Dependencies

pip install -r requirements.txt

3. Install Frontend (optional)

cd admin-frontend
npm install
npm run build
cd ..

4. Configuration

Create a .env file with your settings:

DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_server_id
DISCORD_CHANNEL_ID=your_channel_id
DATABASE_URL=sqlite:///data/fishbowl.db
AI_PROVIDER=openai
AI_API_KEY=your_openai_key
# ... more settings

5. Initialize Database

python -m alembic upgrade head

6. Create Characters

python -m scripts.init_characters

Configuration Guide

Discord Setup

1. Go to https://discord.com/developers/applications
2. Create a new application
3. Go to "Bot" section and create a bot
4. Copy the bot token
5. Enable required permissions and invite to your server

AI Provider Setup

OpenAI

• Get API key from https://platform.openai.com/api-keys
• Recommended models: gpt-4, gpt-3.5-turbo

Anthropic

• Get API key from https://console.anthropic.com/
• Recommended models: claude-3-sonnet-20240229, claude-3-haiku-20240307

Database Setup

SQLite (Default)

• No setup required
• Good for testing and small deployments

PostgreSQL (Recommended)

# Install PostgreSQL
sudo apt install postgresql  # Ubuntu
brew install postgresql      # macOS

# Create database
createdb discord_fishbowl

Redis (Optional)

# Install Redis
sudo apt install redis-server  # Ubuntu
brew install redis            # macOS

# Start Redis
redis-server

Qdrant (Optional)

# Using Docker
docker run -p 6333:6333 qdrant/qdrant

# Or install locally
# See: https://qdrant.tech/documentation/quick-start/

Running the Application

Using Startup Scripts

./start.sh          # Start main application
./start-admin.sh    # Start admin interface

Manual Start

# Main application
python -m src.main

# Admin interface
python -m src.admin.app

Verification

Check Application Status

# Check logs
tail -f logs/fishbowl.log

# Check database
python -c "from src.database.connection import test_connection; test_connection()"

# Check AI provider
python -c "from src.llm.client import test_client; test_client()"

Access Admin Interface

• Open http://localhost:8000/admin
• Login with credentials from setup

Discord Integration

• Invite bot to your server
• Verify bot appears online
• Check configured channel for activity

Troubleshooting

Common Issues

"Module not found" errors

# Ensure virtual environment is activated
source venv/bin/activate

# Ensure PYTHONPATH is set
export PYTHONPATH=$(pwd):$PYTHONPATH

Database connection errors

# Test database connection
python -c "from src.database.connection import get_db_session; print('DB OK')"

# Reset database
python -m alembic downgrade base
python -m alembic upgrade head

Bot not responding

• Verify bot token is correct
• Check bot has required permissions
• Ensure guild_id and channel_id are correct
• Check bot is online in Discord

Memory/Performance issues

• Reduce CONVERSATION_FREQUENCY
• Lower MAX_CONVERSATION_LENGTH
• Use PostgreSQL instead of SQLite
• Enable Redis for caching

Getting Help

1. Check the logs in logs/ directory
2. Verify configuration in .env file
3. Test individual components
4. Check Discord permissions
5. Verify API keys and external services

Advanced Configuration

Character Customization

Edit config/characters.yaml to modify character personalities and behaviors.

System Tuning

Adjust these settings in .env:

• CONVERSATION_FREQUENCY - How often characters talk
• RESPONSE_DELAY_MIN/MAX - Realistic response timing
• MEMORY_RETENTION_DAYS - How long memories persist
• CREATIVITY_BOOST - Enable more creative responses

Production Deployment

• Use PostgreSQL database
• Enable Redis caching
• Set up Qdrant vector database
• Configure proper logging levels
• Set ENVIRONMENT=production
• Use process manager (systemd, supervisor)
• Set up monitoring and backups

Security Notes

• Keep API keys secure and never commit them
• Use strong passwords for admin interface
• Run on internal networks when possible
• Monitor for unusual activity
• Regularly update dependencies
• Enable safety monitoring features