HUGGING_FACE_DEPLOYMENT.md

🚀 Rating Prediction System - Hugging Face Spaces Deployment

A production-ready FastAPI application for predicting product ratings from Vietnamese comments using PhoBERT. This Space uses Docker SDK for deploying heavy ML models (>500MB) with 16GB RAM.

---

🎯 Features

• 🤖 ML-Powered Predictions: PhoBERT-based sentiment analysis
• 📊 Interactive Dashboard: Real-time visualizations with Chart.js
• 💬 Batch Processing: Upload CSV files for bulk predictions
• 🔐 Secure Authentication: JWT-based user management
• 📈 Analytics: Word clouds and rating distributions
• 🗄️ External Database: PostgreSQL support (Render/Neon)

---

🔧 Configuration Required

Required Environment Variables

CRITICAL: Before deploying to Hugging Face Spaces, you MUST add these environment variables in the Settings tab:

1. DATABASE_URL (REQUIRED)

DATABASE_URL=postgresql://username:password@host:port/database

Real External Db url

DATABASE_URL=postgresql://rating_prediction_user:2p3Xv9mKFt3DDFs9OVWDrw8ARHkevTSw@dpg-d4mfq13uibrs738i6jl0-a.singapore-postgres.render.com/rating_prediction

Example from Render:

DATABASE_URL=postgresql://user:pass@dpg-xxxxx.oregon-postgres.render.com/dbname

Example from Neon:

DATABASE_URL=postgresql://user:pass@ep-xxxxx.us-east-2.aws.neon.tech/dbname?sslmode=require

⚠️ Important Notes:

• The URL MUST start with postgresql:// (NOT postgres://)
• If your provider gives you postgres://, the app will auto-convert it
• Include ?sslmode=require for secure connections (recommended)

2. SECRET_KEY (REQUIRED)

SECRET_KEY=your-super-secret-jwt-key-change-this-in-production-min-32-chars

Generate a secure key:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Real SECRECT_KEY: nz0qzAJoIiRQ3v62SAq8g94JAFtfmf-GSU6dkluKtKA

⚠️ Security:

• NEVER commit this key to Git
• Use a cryptographically secure random string
• Minimum 32 characters recommended

---

📋 Deployment Steps

Step 1: Create a New Space

1. Go to https://huggingface.co/new-space
2. Choose Docker as the SDK
3. Select CPU Basic (16GB RAM - Free)
4. Make the Space Public or Private

Step 2: Configure Environment Variables

1. Go to your Space's Settings tab
2. Scroll to Repository Secrets
3. Add the following secrets:
   • DATABASE_URL → Your PostgreSQL connection string
   • SECRET_KEY → Your JWT secret key

Step 3: Push Your Code

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy your project files
cp -r /path/to/PredictRating/* .

# Commit and push
git add .
git commit -m "Initial deployment"
git push

Step 4: Wait for Build

• Hugging Face will automatically build your Docker image
• Build time: ~5-10 minutes (depending on model size)
• Check build logs in the Logs tab

Step 5: Access Your App

• Your app will be available at: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
• The app runs on port 7860 (handled automatically)

---

🗄️ Database Setup

Option A: Render PostgreSQL (Recommended)

1. Create a free PostgreSQL database on Render
2. Go to Dashboard → New → PostgreSQL
3. Copy the External Database URL
4. Add it as DATABASE_URL in HF Spaces Settings

Option B: Neon PostgreSQL

1. Create a free database on Neon
2. Copy the connection string
3. Ensure it includes ?sslmode=require
4. Add it as DATABASE_URL in HF Spaces Settings

Database Initialization

The app automatically:

• Creates tables on first run
• Supports both SQLite (local dev) and PostgreSQL (production)
• No manual migrations needed

---

🐳 Docker Configuration

Port Requirements

• CRITICAL: Hugging Face Spaces requires port 7860
• The Dockerfile is pre-configured correctly
• DO NOT change the port in CMD instruction

User Permissions

• Hugging Face runs containers as user ID 1000
• The Dockerfile creates a user account
• All files are owned by this user

Storage

• /app/static/uploads/ is writable (for word clouds)
• /app/database/ is writable (for local SQLite fallback)
• Consider using external storage (S3/Cloudinary) for production

---

🧪 Testing Locally Before Deployment

Test with Docker

# Build the Docker image
docker build -t rating-prediction .

# Run with environment variables
docker run -p 7860:7860 \
  -e DATABASE_URL="postgresql://user:pass@host/db" \
  -e SECRET_KEY="your-secret-key" \
  rating-prediction

# Access at http://localhost:7860

Test Database Connection

# Inside container
docker exec -it <container_id> python -c "
from app.database import engine
print('✅ Database connected:', engine.url)
"

---

📊 Monitoring & Logs

View Logs in Hugging Face

1. Go to your Space
2. Click the Logs tab
3. Monitor startup and runtime logs

Expected Startup Messages

🚀 Production Mode: Using PostgreSQL
INFO:     Started server process [1]
INFO:     Uvicorn running on http://0.0.0.0:7860

---

🔒 Security Checklist

• ✅ SECRET_KEY stored as HF Secret (not in code)
• ✅ DATABASE_URL stored as HF Secret (not in code)
• ✅ PostgreSQL uses SSL (sslmode=require)
• ✅ Passwords hashed with bcrypt
• ✅ JWT tokens expire after 24 hours
• ✅ Docker runs as non-root user

---

🐛 Troubleshooting

Issue: "Application startup failed"

Solution: Check logs for database connection errors. Verify DATABASE_URL is correct.

Issue: "502 Bad Gateway"

Solution: App may be starting. Wait 2-3 minutes for heavy model loading.

Issue: "Database connection refused"

Solution: Ensure your PostgreSQL database is accessible from external IPs. Check firewall rules.

Issue: "No module named 'app'"

Solution: Ensure all files are copied correctly. Check Dockerfile WORKDIR is /app.

Issue: "Port 7860 already in use"

Solution: Only relevant for local testing. Stop other containers on that port.

---

📚 API Documentation

Once deployed, access:

• Swagger UI: https://your-space.hf.space/docs
• ReDoc: https://your-space.hf.space/redoc

Key Endpoints

• POST /api/auth/register - Create new user
• POST /api/auth/login - Login and get JWT token
• POST /api/predict/single - Predict single comment
• POST /api/predict/batch - Upload CSV for batch predictions
• GET /api/predict/history - View prediction history

---

🆘 Support

If you encounter issues:

1. Check the Logs tab in your Space
2. Verify environment variables in Settings
3. Test database connection from your local machine
4. Review FastAPI Docs
5. Check Hugging Face Spaces Docs

---

📄 License

This project is deployed under the terms specified in your Space settings.

---

Built with ❤️ using FastAPI, PhoBERT, and Hugging Face Spaces