docs/ENVIRONMENT_SETUP.md

Environment Setup Guide

This guide walks you through setting up the Multi-Language Chat Agent application in different environments.

Quick Start

For the fastest setup, use the automated setup script:

# Development environment
python scripts/setup_environment.py --environment development

# Production environment
python scripts/setup_environment.py --environment production

# Testing environment
python scripts/setup_environment.py --environment testing

Manual Setup

1. Prerequisites

System Requirements

• Python 3.8+: Check with python --version
• PostgreSQL 12+: For persistent data storage
• Redis 6+: For caching and sessions (optional but recommended)
• Git: For version control

Install System Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv postgresql postgresql-contrib redis-server

macOS (with Homebrew):

brew install python postgresql redis

Windows:

• Install Python from python.org
• Install PostgreSQL from postgresql.org
• Install Redis from GitHub releases or use WSL

2. Project Setup

Clone Repository

git clone <repository-url>
cd chat-agent

Create Virtual Environment

python -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate

# Windows:
venv\Scripts\activate

Install Python Dependencies

pip install --upgrade pip
pip install -r requirements.txt

3. Database Setup

PostgreSQL Setup

Create Database and User:

-- Connect to PostgreSQL as superuser
sudo -u postgres psql

-- Create database and user
CREATE DATABASE chat_agent_db;
CREATE USER chatuser WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE chat_agent_db TO chatuser;

-- For development, you might want to create separate databases
CREATE DATABASE chat_agent_dev;
CREATE DATABASE chat_agent_test;
GRANT ALL PRIVILEGES ON DATABASE chat_agent_dev TO chatuser;
GRANT ALL PRIVILEGES ON DATABASE chat_agent_test TO chatuser;

\q

Test Connection:

psql -h localhost -U chatuser -d chat_agent_db -c "SELECT version();"

Redis Setup

Start Redis:

# Linux (systemd)
sudo systemctl start redis
sudo systemctl enable redis

# macOS
brew services start redis

# Manual start
redis-server

Test Connection:

redis-cli ping
# Should return: PONG

4. Environment Configuration

Create Environment File

Copy the appropriate environment template:

# Development
cp config/development.env .env

# Production
cp config/production.env .env

# Testing
cp config/testing.env .env

Configure Environment Variables

Edit .env file with your actual values:

# Required Configuration
GROQ_API_KEY=your_groq_api_key_here
SECRET_KEY=your_secure_secret_key_here

# Database Configuration
DATABASE_URL=postgresql://chatuser:your_password@localhost:5432/chat_agent_db

# Redis Configuration (optional)
REDIS_URL=redis://localhost:6379/0

# Application Configuration
FLASK_ENV=development  # or production
FLASK_DEBUG=True       # False for production

Generate Secret Key

# Generate a secure secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"

5. Database Initialization

Run Migrations

# Initialize database with schema
python scripts/init_db.py init --config development

# Check migration status
python scripts/init_db.py status --config development

# Seed with sample data (optional)
python scripts/init_db.py seed --config development

Manual Migration (Alternative)

python migrations/migrate.py migrate --config development

6. Application Startup

Development Server

python app.py

The application will be available at http://localhost:5000

Production Server

# Install production server
pip install gunicorn

# Start with Gunicorn
gunicorn --bind 0.0.0.0:5000 --workers 4 --worker-class eventlet app:app

7. Verification

Test Health Endpoints

# Basic health check
curl http://localhost:5000/health/

# Detailed health check
curl http://localhost:5000/health/detailed

# Expected response:
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "service": "chat-agent",
  "version": "1.0.0"
}

Test Chat Interface

1. Open browser to http://localhost:5000
2. You should see the chat interface
3. Try sending a message
4. Verify WebSocket connection works

Test API Endpoints

# Test session creation
curl -X POST http://localhost:5000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test_user", "language": "python"}'

# Test language switching
curl -X PUT http://localhost:5000/api/sessions/SESSION_ID/language \
  -H "Content-Type: application/json" \
  -d '{"language": "javascript"}'

Environment-Specific Configuration

Development Environment

Features:

• Debug mode enabled
• Detailed logging
• Hot reload
• Development database
• Relaxed security settings

Configuration:

FLASK_ENV=development
FLASK_DEBUG=True
LOG_LEVEL=DEBUG
DATABASE_URL=postgresql://chatuser:password@localhost:5432/chat_agent_dev

Additional Tools:

# Install development tools
pip install flask-debugtoolbar ipdb watchdog

# Enable debug toolbar
export FLASK_DEBUG_TB_ENABLED=True

Production Environment

Features:

• Debug mode disabled
• Optimized logging
• Production database
• Enhanced security
• Performance monitoring

Configuration:

FLASK_ENV=production
FLASK_DEBUG=False
LOG_LEVEL=INFO
DATABASE_URL=postgresql://user:pass@prod-host:5432/chat_agent_prod
SECRET_KEY=very_secure_secret_key

Security Considerations:

• Use environment variables for secrets
• Enable HTTPS
• Configure firewall
• Set up monitoring
• Regular backups

Testing Environment

Features:

• In-memory database
• Isolated test data
• Fast execution
• Minimal logging

Configuration:

FLASK_ENV=testing
TESTING=True
DATABASE_URL=sqlite:///:memory:
REDIS_URL=redis://localhost:6379/1
LOG_LEVEL=WARNING

Running Tests:

# Set testing environment
export FLASK_ENV=testing

# Run tests
python -m pytest tests/
python -m pytest tests/ --cov=chat_agent

Troubleshooting

Common Issues

1. Import Errors

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

# Reinstall dependencies
pip install -r requirements.txt

2. Database Connection Issues

# Check PostgreSQL service
sudo systemctl status postgresql

# Test connection manually
psql -h localhost -U chatuser -d chat_agent_db

# Check environment variables
echo $DATABASE_URL

3. Redis Connection Issues

# Check Redis service
sudo systemctl status redis

# Test connection
redis-cli ping

# Check Redis URL
echo $REDIS_URL

4. Permission Issues

# Fix file permissions
chmod +x scripts/*.py

# Fix directory permissions
sudo chown -R $USER:$USER .

5. Port Already in Use

# Find process using port 5000
lsof -i :5000

# Kill process
kill -9 PID

# Use different port
export PORT=5001
python app.py

Logging and Debugging

Enable Debug Logging

export LOG_LEVEL=DEBUG
export FLASK_DEBUG=True
python app.py

View Logs

# Application logs
tail -f logs/chat_agent.log

# System logs
journalctl -f -u postgresql
journalctl -f -u redis

Database Debugging

# Connect to database
psql -h localhost -U chatuser -d chat_agent_db

# Check tables
\dt

# Check migrations
SELECT * FROM schema_migrations;

# Check sample data
SELECT * FROM chat_sessions LIMIT 5;

Performance Optimization

Database Optimization

-- Create indexes for better performance
CREATE INDEX CONCURRENTLY idx_messages_session_timestamp 
ON messages(session_id, timestamp);

CREATE INDEX CONCURRENTLY idx_sessions_user_active 
ON chat_sessions(user_id, is_active);

Redis Optimization

# Configure Redis for production
# Edit /etc/redis/redis.conf
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000

Application Optimization

# Use connection pooling
SQLALCHEMY_ENGINE_OPTIONS = {
    'pool_size': 10,
    'pool_recycle': 120,
    'pool_pre_ping': True
}

# Configure Redis connection pool
REDIS_CONNECTION_POOL = {
    'max_connections': 20,
    'retry_on_timeout': True
}

Next Steps

After successful setup:

1. Configure Groq API: Add your actual API key
2. Set up monitoring: Configure health checks and logging
3. Security hardening: Review security settings
4. Performance testing: Test with expected load
5. Backup strategy: Set up database backups
6. Documentation: Document your specific configuration

For deployment to production, see DEPLOYMENT.md.