Hugging Face's logo

Spaces:
findEthics
/
Chatty
Sleeping

App Files Community
Chatty / docs /INSTALLATION.md
findEthics
Optimize UI for mobile devices with minimal design
b4487f6
preview code
|
Raw
History Blame Contribute Delete
8.93 kB

A newer version of the Gradio SDK is available: 6.26.0

Upgrade

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

    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

    python deploy.py setup-dev

  3. Edit Configuration Edit .env file with your MongoDB connection details:

    SECRET_KEY=your-generated-secret-key
MONGODB_URL=your-mongodb-connection-string

  4. Start Application

    ./start.sh

Method 2: Manual Installation

Step 1: System Preparation

Ubuntu/Debian:

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

macOS:

# 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
  2. Install Git from git-scm.com

Step 2: Application Setup

  1. Clone Repository

    git clone <repository-url>
cd chatty

  2. Create Virtual Environment

    python3 -m venv atlas_env

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

# Windows:
atlas_env\Scripts\activate

  3. Install Dependencies

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

    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:

    brew tap mongodb/brew
brew install mongodb-community

    Windows: Download installer from MongoDB Download Center

  2. Start MongoDB Service

    Ubuntu/Debian:

    sudo systemctl start mongod
sudo systemctl enable mongod

    macOS:

    brew services start mongodb/brew/mongodb-community

    Windows: MongoDB runs as a Windows service after installation

  3. Create Database and User

    mongosh

    use chatty
db.createUser({
  user: "chatty_user",
  pwd: "your_secure_password",
  roles: [{ role: "readWrite", db: "chatty" }]
})

Step 4: Configuration

  1. Generate Configuration

    python deploy.py setup-dev

  2. Edit Environment File Edit .env file:

    For MongoDB Atlas:

    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:

    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

    python deploy.py gen-secret

    Copy the generated key to your .env file.

Step 5: Validation and Testing

  1. Validate Configuration

    python config.py

  2. Test Database Connection

    python -c "from database import test_connection; test_connection()"

  3. Run Tests (Optional)

    pip install -r Test/test_requirements.txt
python Test/run_tests.py

Step 6: Start Application

  1. Start with Script

    chmod +x start.sh
./start.sh

  2. Or Start Manually

    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

    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:

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

Troubleshooting

Common Installation Issues

  1. Python Version Issues

    python --version  # Should be 3.8+
python3 --version

  2. Virtual Environment Issues

    # 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

    # Test connection manually
python -c "
from pymongo import MongoClient
client = MongoClient('your-connection-string')
print(client.admin.command('ping'))
"

  4. Permission Issues (Linux/macOS)

    chmod +x start.sh
chmod +x deploy.py

  5. Port Already in Use

    # 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

    python deploy.py check-prod  # Even for development
python config.py

  3. Test Components

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

    # 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
    use chatty
db.dropDatabase()

  4. Remove System Dependencies (Optional)

    • Uninstall MongoDB if no longer needed
    • Remove Python if installed specifically for this application