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:

```bash
# 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:**
```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv postgresql postgresql-contrib redis-server
```

**macOS (with Homebrew):**
```bash
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

```bash
git clone <repository-url>
cd chat-agent
```

#### Create Virtual Environment

```bash
python -m venv venv

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

# Windows:
venv\Scripts\activate
```

#### Install Python Dependencies

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

### 3. Database Setup

#### PostgreSQL Setup

**Create Database and User:**

```sql
-- 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:**

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

#### Redis Setup

**Start Redis:**

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

# macOS
brew services start redis

# Manual start
redis-server
```

**Test Connection:**

```bash
redis-cli ping
# Should return: PONG
```

### 4. Environment Configuration

#### Create Environment File

Copy the appropriate environment template:

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

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

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

### 5. Database Initialization

#### Run Migrations

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

```bash
python migrations/migrate.py migrate --config development
```

### 6. Application Startup

#### Development Server

```bash
python app.py
```

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

#### Production Server

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

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

```bash
# 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:**
```bash
FLASK_ENV=development
FLASK_DEBUG=True
LOG_LEVEL=DEBUG
DATABASE_URL=postgresql://chatuser:password@localhost:5432/chat_agent_dev
```

**Additional Tools:**
```bash
# 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:**
```bash
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:**
```bash
FLASK_ENV=testing
TESTING=True
DATABASE_URL=sqlite:///:memory:
REDIS_URL=redis://localhost:6379/1
LOG_LEVEL=WARNING
```

**Running Tests:**
```bash
# 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

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

# Reinstall dependencies
pip install -r requirements.txt
```

#### 2. Database Connection Issues

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

```bash
# Check Redis service
sudo systemctl status redis

# Test connection
redis-cli ping

# Check Redis URL
echo $REDIS_URL
```

#### 4. Permission Issues

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

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

#### 5. Port Already in Use

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

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

#### View Logs

```bash
# Application logs
tail -f logs/chat_agent.log

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

#### Database Debugging

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

```sql
-- 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

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

```python
# 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](DEPLOYMENT.md).