docs/INSTALLATION.md

# Chatty Installation Guide

This guide provides step-by-step instructions for installing and configuring the Chatty application.

## System Requirements

- **Python**: 3.8 or higher
- **Database**: MongoDB (Atlas recommended) or local MongoDB installation
- **Memory**: Minimum 512MB RAM
- **Storage**: 100MB free space
- **Network**: Internet connection for external API calls

## Installation Methods

### Method 1: Quick Start (Recommended)

1. **Clone and Setup**
   ```bash
   git clone <repository-url>
   cd chatty
   python -m venv atlas_env
   source atlas_env/bin/activate  # Windows: atlas_env\Scripts\activate
   pip install -r requirements.txt
   ```

2. **Configure Environment**
   ```bash
   python deploy.py setup-dev
   ```

3. **Edit Configuration**
   Edit `.env` file with your MongoDB connection details:
   ```env
   SECRET_KEY=your-generated-secret-key
   MONGODB_URL=your-mongodb-connection-string
   ```

4. **Start Application**
   ```bash
   ./start.sh
   ```

### Method 2: Manual Installation

#### Step 1: System Preparation

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

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

**Windows:**
1. Install Python from [python.org](https://python.org)
2. Install Git from [git-scm.com](https://git-scm.com)

#### Step 2: Application Setup

1. **Clone Repository**
   ```bash
   git clone <repository-url>
   cd chatty
   ```

2. **Create Virtual Environment**
   ```bash
   python3 -m venv atlas_env
   
   # Activate virtual environment
   # Linux/macOS:
   source atlas_env/bin/activate
   
   # Windows:
   atlas_env\Scripts\activate
   ```

3. **Install Dependencies**
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

#### Step 3: Database Setup

Choose one of the following database options:

**Option A: MongoDB Atlas (Cloud - Recommended)**

1. Create account at [MongoDB Atlas](https://www.mongodb.com/atlas)
2. Create new cluster (free tier available)
3. Create database user:
   - Username: `chatty_user`
   - Password: Generate secure password
   - Roles: `readWrite` on your database
4. Configure network access:
   - Add your IP address
   - Or allow access from anywhere (0.0.0.0/0) for development
5. Get connection string from "Connect" → "Connect your application"

**Option B: Local MongoDB**

1. **Install MongoDB**
   
   **Ubuntu/Debian:**
   ```bash
   wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
   echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
   sudo apt update
   sudo apt install -y mongodb-org
   ```
   
   **macOS:**
   ```bash
   brew tap mongodb/brew
   brew install mongodb-community
   ```
   
   **Windows:**
   Download installer from [MongoDB Download Center](https://www.mongodb.com/try/download/community)

2. **Start MongoDB Service**
   
   **Ubuntu/Debian:**
   ```bash
   sudo systemctl start mongod
   sudo systemctl enable mongod
   ```
   
   **macOS:**
   ```bash
   brew services start mongodb/brew/mongodb-community
   ```
   
   **Windows:**
   MongoDB runs as a Windows service after installation

3. **Create Database and User**
   ```bash
   mongosh
   ```
   ```javascript
   use chatty
   db.createUser({
     user: "chatty_user",
     pwd: "your_secure_password",
     roles: [{ role: "readWrite", db: "chatty" }]
   })
   ```

#### Step 4: Configuration

1. **Generate Configuration**
   ```bash
   python deploy.py setup-dev
   ```

2. **Edit Environment File**
   Edit `.env` file:
   
   **For MongoDB Atlas:**
   ```env
   SECRET_KEY=your-generated-secret-key
   MONGODB_URL=mongodb+srv://chatty_user:password@cluster.mongodb.net/chatty?retryWrites=true&w=majority
   MONGODB_DATABASE=chatty
   FLASK_ENV=development
   ```
   
   **For Local MongoDB:**
   ```env
   SECRET_KEY=your-generated-secret-key
   MONGODB_URL=mongodb://chatty_user:password@localhost:27017/chatty
   MONGODB_DATABASE=chatty
   FLASK_ENV=development
   ```

3. **Generate Secret Key**
   ```bash
   python deploy.py gen-secret
   ```
   Copy the generated key to your `.env` file.

#### Step 5: Validation and Testing

1. **Validate Configuration**
   ```bash
   python config.py
   ```

2. **Test Database Connection**
   ```bash
   python -c "from database import test_connection; test_connection()"
   ```

3. **Run Tests (Optional)**
   ```bash
   pip install -r Test/test_requirements.txt
   python Test/run_tests.py
   ```

#### Step 6: Start Application

1. **Start with Script**
   ```bash
   chmod +x start.sh
   ./start.sh
   ```

2. **Or Start Manually**
   ```bash
   python app.py
   ```

3. **Access Application**
   Open browser to: http://localhost:7860

## Post-Installation Setup

### Create First User Account

1. Navigate to http://localhost:7860
2. Click "Register" to create your first account
3. Fill in email and password
4. Log in with your credentials

### Verify Installation

1. **Check Application Health**
   ```bash
   curl http://localhost:7860/health
   ```

2. **Test Authentication**
   - Register a new account
   - Log in and out
   - Send a test chat message

3. **Check Logs**
   Monitor console output for any errors

## Configuration Options

### Environment Variables

Create or edit `.env` file with these options:

```env
# Required
SECRET_KEY=your-64-character-secret-key
MONGODB_URL=your-mongodb-connection-string
MONGODB_DATABASE=chatty

# Optional
FLASK_ENV=development
SESSION_LIFETIME_HOURS=24
MAX_LOGIN_ATTEMPTS=5
RATE_LIMIT_WINDOW=900
API_TIMEOUT=30
LOG_LEVEL=INFO
PORT=7860
```

### Advanced Configuration

For production deployment, see [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md).

## Troubleshooting

### Common Installation Issues

1. **Python Version Issues**
   ```bash
   python --version  # Should be 3.8+
   python3 --version
   ```

2. **Virtual Environment Issues**
   ```bash
   # Recreate virtual environment
   rm -rf atlas_env
   python3 -m venv atlas_env
   source atlas_env/bin/activate
   pip install -r requirements.txt
   ```

3. **MongoDB Connection Issues**
   ```bash
   # Test connection manually
   python -c "
   from pymongo import MongoClient
   client = MongoClient('your-connection-string')
   print(client.admin.command('ping'))
   "
   ```

4. **Permission Issues (Linux/macOS)**
   ```bash
   chmod +x start.sh
   chmod +x deploy.py
   ```

5. **Port Already in Use**
   ```bash
   # Find process using port 7860
   lsof -i :7860
   # Kill process or change PORT in .env
   ```

### Error Messages

**"MONGODB_URL environment variable is required"**
- Check `.env` file exists and contains `MONGODB_URL`
- Verify environment variable is set correctly

**"Configuration validation failed"**
- Run `python config.py` to see specific issues
- Check all required environment variables are set

**"Database connection failed"**
- Verify MongoDB is running (local) or accessible (Atlas)
- Check connection string format
- Verify credentials and network access

**"Secret key errors"**
- Generate new secret key: `python deploy.py gen-secret`
- Ensure key is at least 32 characters long

### Getting Help

1. **Check Logs**
   - Console output during startup
   - Application logs if `LOG_FILE` is configured

2. **Validate Setup**
   ```bash
   python deploy.py check-prod  # Even for development
   python config.py
   ```

3. **Test Components**
   ```bash
   # Test database
   python -c "from database import test_connection; test_connection()"
   
   # Test configuration
   python -c "from config import validate_environment; validate_environment()"
   ```

## Next Steps

After successful installation:

1. **Production Deployment**: See [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md)
2. **Customization**: Modify templates and styles in `templates/` and `static/`
3. **Monitoring**: Set up logging and monitoring for production use
4. **Backup**: Configure regular database backups
5. **Updates**: Keep dependencies updated with `pip install -r requirements.txt --upgrade`

## Uninstallation

To remove the application:

1. **Stop Application**
   - Press Ctrl+C if running in terminal
   - Or stop systemd service if configured

2. **Remove Files**
   ```bash
   # Remove application directory
   rm -rf /path/to/chatty
   
   # Remove virtual environment
   rm -rf atlas_env
   ```

3. **Remove Database** (Optional)
   - For MongoDB Atlas: Delete cluster from Atlas dashboard
   - For local MongoDB: Drop database in MongoDB shell
   ```javascript
   use chatty
   db.dropDatabase()
   ```

4. **Remove System Dependencies** (Optional)
   - Uninstall MongoDB if no longer needed
   - Remove Python if installed specifically for this application