Hugging Face's logo

Spaces:
findEthics
/
Atlas
Sleeping

App Files Community
Atlas / docs /deployment /DEPLOYMENT.md
findEthics
Complete codebase cleanup and project structure validation
f0b765c
preview code
|
Raw
History Blame Contribute Delete
14.9 kB

🚀 Hugging Face Deployment Guide

✅ Deployment Readiness Status

Your Atlas Chat application with analytics is READY FOR DEPLOYMENT to Hugging Face Spaces!

✅ What's Working:

  • ✅ Complete Analytics System - Session tracking, message analytics, interactive dashboard
  • ✅ MongoDB Integration - Full MongoDB Atlas support with automatic fallback
  • ✅ Interactive Dashboard - Real-time charts with Chart.js visualizations
  • ✅ Data Export - JSON/CSV export with date range filtering
  • ✅ Docker Configuration - Optimized Python 3.9 slim image
  • ✅ CORS Setup - Configured for Hugging Face domains (*.hf.space)
  • ✅ Security - Environment variables properly secured
  • ✅ Performance Monitoring - Response time tracking and error analytics
  • ✅ Search Engine Integration - Brave Search + DuckDuckGo with fallback

🔧 Pre-Deployment Setup

1. Environment Variables Required

You'll need to set these in your Hugging Face Space settings:

# Required for AI functionality
GOOGLE_API_KEY=your_google_api_key_here

# Optional but recommended for search (falls back to DuckDuckGo only)
BRAVE_API_KEY=your_brave_search_api_key_here

# Optional for persistent analytics (will use in-memory storage if not provided)
MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority&appName=Atlas
MONGODB_DATABASE=Atlas

⚠️ Important Notes:

  • GOOGLE_API_KEY is required - the app won't work without it
  • BRAVE_API_KEY is optional - search will work with DuckDuckGo only if not provided
  • MONGODB_URL is optional - analytics will use in-memory storage if not provided (data lost on restart)
  • For production use, MongoDB is highly recommended for persistent analytics

2. Files to Upload

Upload these files to your Hugging Face Space:

Required Files:

  • app.py - Main FastAPI application
  • requirements.txt - Python dependencies
  • Dockerfile - Container configuration
  • analytics/ - Complete analytics module directory
    • analytics/__init__.py
    • analytics/database.py
    • analytics/models.py
    • analytics/collectors.py
    • analytics/dashboard.py

Optional Documentation:

  • README.md - Project documentation
  • SETUP.md - Setup instructions

DO NOT UPLOAD:

  • .env file (contains sensitive API keys)
  • test_*.py files (testing scripts)
  • debug_*.py files (debug utilities)
  • atlas_env/ (virtual environment)
  • __pycache__/ (Python cache files)
  • .git/ (git repository data)

🚀 Deployment Steps

Step 1: Create Hugging Face Space

  1. Go to Hugging Face Spaces
  2. Click "Create new Space"
  3. Choose:
    • Name: atlas-chat-analytics
    • License: Apache 2.0
    • SDK: Docker
    • Hardware: CPU Basic (free tier)

Step 2: Configure Environment Variables

  1. In your Space settings, go to "Variables and secrets"

  2. Add the environment variables (click "New secret" for each):

    Required:

    Name: GOOGLE_API_KEY
Value: your_actual_google_api_key_from_google_ai_studio

    Optional but Recommended:

    Name: BRAVE_API_KEY
Value: your_actual_brave_search_api_key

Name: MONGODB_URL
Value: mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority&appName=Atlas

Name: MONGODB_DATABASE
Value: Atlas

  3. Important: Use "Secret" type for all API keys to keep them secure

Step 3: Upload Files

  1. Upload all necessary files (see list above)
  2. The Space will automatically build using the Dockerfile
  3. Wait for the build to complete (usually 5-10 minutes)

Step 4: Test Deployment

Once deployed, test these endpoints:

Core Functionality:

  • Health Check: https://your-space-name.hf.space/
  • API Documentation: https://your-space-name.hf.space/docs
  • Chat API: https://your-space-name.hf.space/chat (POST request)
  • Search API: https://your-space-name.hf.space/search (POST request)

Analytics Endpoints:

  • Interactive Dashboard: https://your-space-name.hf.space/analytics/dashboard
  • Basic Stats API: https://your-space-name.hf.space/analytics/stats
  • Data Export (JSON): https://your-space-name.hf.space/analytics/export?format=json&days=7
  • Data Export (CSV): https://your-space-name.hf.space/analytics/export?format=csv&days=7

For your deployed Atlas app, the actual URLs are:

  • Interactive Dashboard: https://findethics-atlas.hf.space/analytics/dashboard
  • Basic Stats API: https://findethics-atlas.hf.space/analytics/stats
  • Data Export (JSON): https://findethics-atlas.hf.space/analytics/export?format=json&days=7
  • Data Export (CSV): https://findethics-atlas.hf.space/analytics/export?format=csv&days=7

Testing Commands:

# Test health endpoint
curl https://findethics-atlas.hf.space/

# Test chat functionality
curl -X POST https://findethics-atlas.hf.space/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, how are you?", "use_search": true}'

# Test analytics endpoints
curl https://findethics-atlas.hf.space/analytics/stats
curl https://findethics-atlas.hf.space/analytics/export?format=json&days=1

📊 Analytics System Overview

Your Atlas application includes a comprehensive analytics system with multiple endpoints and features:

🔗 Analytics Endpoints

1. Interactive Dashboard

  • URL: (Analytics Dashbaord)[https://findethics-atlas.hf.space/analytics/dashboard]
  • Method: GET
  • Description: Full HTML dashboard with interactive charts and real-time metrics
  • Features:
    • Real-time statistics cards (total messages, sessions, active users)
    • Hourly message activity charts (last 24 hours)
    • Performance metrics visualization (P50, P90, P95 response times)
    • Search usage analytics
    • Auto-refresh functionality
    • Responsive design for mobile/desktop

2. Basic Statistics API

  • URL: https://findethics-atlas.hf.space/analytics/stats
  • Method: GET
  • Response: JSON
  • Description: Core analytics metrics in JSON format
  • Data Includes:
    {
  "total_sessions": 150,
  "total_messages": 1250,
  "messages_today": 45,
  "messages_week": 320,
  "active_sessions": 12,
  "search_usage_percentage": 78.5,
  "average_response_time_ms": 1250,
  "last_updated": "2024-01-15T10:30:00Z"
}

3. Data Export (JSON Format)

  • URL: https://findethics-atlas.hf.space/analytics/export?format=json&days=7
  • Method: GET
  • Parameters:
    • format: "json" (required)
    • days: Number of days to export (default: 7)
  • Description: Export raw analytics data in JSON format
  • Use Cases: Data analysis, backup, integration with external tools

4. Data Export (CSV Format)

  • URL: https://findethics-atlas.hf.space/analytics/export?format=csv&days=7
  • Method: GET
  • Parameters:
    • format: "csv" (required)
    • days: Number of days to export (default: 7)
  • Description: Export analytics data in CSV format for spreadsheet analysis
  • Use Cases: Excel analysis, reporting, data visualization tools

🎯 Dashboard Features

  • Real-time Statistics: Total messages, sessions, active users
  • Interactive Charts: Hourly activity trends, performance metrics
  • Visual Analytics: Chart.js powered visualizations
  • Search Analytics: Usage patterns and search engine performance
  • Export Functionality: Download data in JSON/CSV with date filtering
  • Responsive Design: Works on desktop and mobile devices

🔍 Monitoring Capabilities

  • Session Management: Unique session tracking with UUIDs
  • Performance Monitoring: Response time percentiles (P50, P90, P95)
  • Search Engine Analytics: Brave vs DuckDuckGo performance comparison
  • Error Rate Tracking: Success/failure rates and error messages
  • User Engagement: Messages per session, search usage patterns
  • Real-time Updates: Dashboard refreshes with live data

📈 Data Collection

  • Session Data: Start time, duration, message count, user agent
  • Message Metrics: Prompt/response length, processing time, search usage
  • Performance Data: Response times, error rates, search engine performance
  • Search Analytics: Query terms, result counts, engine fallback usage

🛠️ API Usage Examples

Testing Basic Stats 

curl https://findethics-atlas.hf.space/analytics/stats

Exporting Last 30 Days (JSON) 

curl "https://findethics-atlas.hf.space/analytics/export?format=json&days=30" > analytics_data.json

Exporting Last Week (CSV) 

curl "https://findethics-atlas.hf.space/analytics/export?format=csv&days=7" > analytics_data.csv

JavaScript Integration 

// Fetch basic stats
fetch('https://findethics-atlas.hf.space/analytics/stats')
  .then(response => response.json())
  .then(data => console.log('Analytics:', data));

// Export data
fetch('https://findethics-atlas.hf.space/analytics/export?format=json&days=7')
  .then(response => response.json())
  .then(data => console.log('Export data:', data));

🛠️ Troubleshooting

Common Issues:

  1. Build Fails

    • Check that all required files are uploaded (especially analytics/ directory)
    • Verify Dockerfile syntax and Python version compatibility
    • Ensure requirements.txt includes all dependencies (motor, google-generativeai, etc.)
    • Check for any syntax errors in Python files

  2. Application Won't Start

    • Verify GOOGLE_API_KEY is set (required for startup)
    • Check logs for import errors or missing dependencies
    • Ensure port 7860 is properly exposed in Dockerfile

  3. Analytics Not Working

    • If MongoDB not available, analytics will use in-memory storage (data lost on restart)
    • Check MONGODB_URL format: mongodb+srv://user:pass@cluster.mongodb.net/...
    • Verify MongoDB Atlas cluster is running and accessible
    • Check IP whitelist in MongoDB Atlas (allow all IPs: 0.0.0.0/0 for Hugging Face)

  4. API Keys Not Working

    • Ensure environment variables are set as "Secrets" in Space settings
    • Check API key validity and quotas (Google AI Studio, Brave Search)
    • Verify variable names match exactly (case-sensitive)
    • Test API keys locally before deployment

  5. Search Not Working

    • If BRAVE_API_KEY not set, only DuckDuckGo will be used
    • Check Brave Search API quota and rate limits
    • Verify network connectivity from Hugging Face servers

  6. Dashboard Not Loading

    • Check browser console for JavaScript errors
    • Verify Chart.js CDN is accessible
    • Test analytics endpoints directly: /analytics/stats

🔒 Security Notes

  • ✅ Environment Variables: All API keys stored as secrets in Hugging Face
  • ✅ No Hardcoded Secrets: All sensitive data loaded from environment
  • ✅ CORS Configuration: Restricted to Hugging Face domains (*.hf.space)
  • ✅ File Security: .env and sensitive files excluded from deployment
  • ✅ MongoDB Security: Connection strings properly secured
  • ✅ User Isolation: Docker runs with non-root user (uid 1000)
  • ✅ Input Validation: Pydantic models validate all API inputs
  • ✅ Error Handling: Sensitive information not exposed in error messages

📈 Performance Optimization

The application is optimized for Hugging Face Spaces:

🐳 Docker Optimization

  • Base Image: Python 3.9 slim for minimal footprint
  • Non-root User: Security and resource isolation
  • Layer Caching: Optimized Dockerfile layer ordering
  • Dependency Management: No-cache pip installs to reduce image size

⚡ Application Performance

  • Async Operations: FastAPI with async/await for concurrent requests
  • Connection Pooling: Motor MongoDB driver with connection reuse
  • Search Optimization: Concurrent search engine queries with timeouts
  • Error Handling: Graceful fallbacks prevent cascading failures
  • Resource Management: Efficient memory usage with proper cleanup

📊 Analytics Optimization

  • In-memory Caching: Active sessions cached for quick access
  • Batch Operations: Efficient database writes
  • Lazy Loading: Dashboard data loaded on-demand
  • Fallback Storage: Graceful degradation if MongoDB unavailable

🔍 Search Performance

  • Dual Engine Strategy: Brave + DuckDuckGo with concurrent execution
  • Timeout Management: Prevents hanging requests
  • Result Deduplication: Efficient URL-based deduplication
  • NLP Optimization: Cached spaCy models and NLTK data

🎉 Post-Deployment

After successful deployment:

✅ Immediate Testing

  1. Health Check: Verify the app is running at your Space URL
  2. Chat Functionality: Test chat requests with and without search
  3. Analytics Dashboard: Check the interactive dashboard is working
  4. API Endpoints: Test all endpoints using the /docs interface

📊 Monitoring Setup

  1. Analytics Dashboard: Monitor usage at /analytics/dashboard
  2. Performance Metrics: Track response times and error rates
  3. Search Analytics: Monitor search engine performance
  4. User Engagement: Track session duration and message patterns

🔧 Optimization

  1. Monitor Resource Usage: Check CPU/memory usage in Space logs
  2. Scale Hardware: Upgrade to CPU Basic/GPU if needed for high traffic
  3. Database Performance: Monitor MongoDB Atlas performance metrics
  4. API Rate Limits: Monitor Google AI and Brave Search quotas

📈 Growth Considerations

  • Hardware Scaling: Upgrade Hugging Face Space tier for more traffic
  • Database Scaling: Consider MongoDB Atlas cluster scaling
  • CDN Integration: For global performance optimization
  • Monitoring Tools: Integrate external monitoring (DataDog, New Relic)

🚀 Success Metrics

  • Uptime: Monitor application availability
  • Response Times: Track P95 response times < 2 seconds
  • Error Rates: Keep error rates < 1%
  • User Engagement: Track daily active users and session duration

Your Atlas Chat application with comprehensive analytics is now ready for production deployment on Hugging Face Spaces! 🚀

📋 Deployment Checklist

  • Hugging Face Space created with Docker SDK
  • All required files uploaded (app.py, requirements.txt, Dockerfile, analytics/)
  • Environment variables configured as secrets
  • GOOGLE_API_KEY set (required)
  • BRAVE_API_KEY set (optional but recommended)
  • MONGODB_URL set (optional but recommended for persistence)
  • Application builds successfully
  • Health endpoint responds correctly
  • Chat functionality works
  • Analytics dashboard loads
  • Search engines working (Brave + DuckDuckGo)
  • Data export functionality tested
  • Performance monitoring in place