DEPLOYMENT.md

Domify Academy Super Bot - Deployment Guide

Overview

This guide provides step-by-step instructions for deploying the Domify Academy Super Bot to Hugging Face Spaces using Docker.

---

Prerequisites

Before deploying, ensure you have:

1. Hugging Face Account - Create one at huggingface.co
2. NVIDIA API Key - Get from NVIDIA API Portal
3. Database - MySQL/TiDB database URL
4. Optional: Google Sheets API Key - For feedback logging

---

Step 1: Create a Hugging Face Space

1. Go to huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: domify-academy-bot
   • License: Apache 2.0 (or your choice)
   • SDK: Select "Docker"
   • Visibility: Public or Private (your choice)
4. Click "Create Space"

---

Step 2: Prepare Your Repository

Create a .gitignore file to exclude sensitive files:

node_modules/
dist/
.env
.env.local
.env.*.local
*.log
.DS_Store
.vscode/
.idea/

Initialize a Git repository and push to Hugging Face:

cd /path/to/domify-academy-bot
git init
git add .
git commit -m "Initial commit: Domify Academy Super Bot"
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/domify-academy-bot
git push -u origin main

---

Step 3: Set Environment Variables

In your Hugging Face Space settings, add the following secrets:

Variable	Description	Example
DATABASE_URL	MySQL connection string	mysql://user:pass@host:3306/db
NVIDIA_API_KEY	NVIDIA API key for LLM/image models	nvapi-xxxxx
JWT_SECRET	Secret for session tokens	Generate with openssl rand -base64 32
GOOGLE_SHEETS_API_KEY	(Optional) Google Sheets API key	AIzaSyD...
GOOGLE_SHEETS_ID	(Optional) Google Sheet ID	1BxiMVs0XRA5nFMKUVfIKWWY...
NODE_ENV	Environment	production

To set secrets in Hugging Face:

1. Go to your Space settings
2. Scroll to "Repository secrets"
3. Add each variable as a secret

---

Step 4: Configure Docker Build

The Dockerfile is already configured for Hugging Face Spaces. Key features:

• Multi-stage build for optimized image size
• Production dependencies only to reduce footprint
• Health check to monitor application status
• Non-root user for security
• Port 7860 (Hugging Face standard)

---

Step 5: Deploy

Once you push to the repository, Hugging Face automatically:

1. Detects the Dockerfile
2. Builds the Docker image
3. Deploys the container
4. Assigns a public URL

Monitor the build:

1. Go to your Space page
2. Click the "Build" tab
3. Watch the logs for any errors

---

Step 6: Verify Deployment

Once deployed, test the application:

# Check health endpoint
curl https://YOUR_SPACE_URL/api/health

# Expected response:
# {
#   "status": "healthy",
#   "uptime": 123.45,
#   "database": "connected"
# }

---

Environment Variables Reference

Required Variables

• DATABASE_URL: MySQL connection string

  • Format: mysql://user:password@host:port/database
  • Example: mysql://admin:secret@db.example.com:3306/domify_bot

• NVIDIA_API_KEY: API key for NVIDIA models

  • Get from: NVIDIA Build Portal
  • Used for: Llama-3 70B, SDXL, Flux, Video generation

• JWT_SECRET: Secret for signing session tokens

  • Generate: openssl rand -base64 32
  • Keep secure and don't share

Optional Variables

• GOOGLE_SHEETS_API_KEY: For feedback logging to Google Sheets
• GOOGLE_SHEETS_ID: ID of the target Google Sheet
• RATE_LIMIT_REQUESTS: Requests per minute (default: 30)
• RATE_LIMIT_WINDOW: Rate limit window in seconds (default: 3600)

---

Database Setup

MySQL Schema

The application automatically creates tables on first run. Required tables:

• users - User accounts and authentication
• conversations - Chat conversations
• messages - Individual messages
• images - Generated images
• feedback - User feedback and ratings

Connection String Format

mysql://username:password@hostname:port/database_name

Example with TiDB (recommended for Hugging Face):

mysql://root:password@tidb-cluster.tidb.cloud:4000/domify_bot?sslMode=REQUIRE

---

Monitoring and Logs

View Logs

In Hugging Face Space:

1. Go to "Logs" tab
2. Filter by date/time
3. Search for errors or specific operations

Common Issues

Issue	Solution
Database connection failed	Verify DATABASE_URL and network access
NVIDIA API errors	Check NVIDIA_API_KEY validity and quota
Out of memory	Increase Space compute resources
Rate limit errors	Adjust RATE_LIMIT_REQUESTS or upgrade tier

---

Performance Optimization

Caching

The application uses in-memory caching for:

• Search results (5 minutes TTL)
• User sessions (30 minutes TTL)
• Generated images (1 hour TTL)

Database Optimization

• Add indexes on frequently queried columns
• Archive old conversations periodically
• Monitor query performance

Scaling

For high traffic:

1. Upgrade Space compute to more powerful GPU
2. Use Redis for distributed caching
3. Implement database connection pooling
4. Enable CDN for static assets

---

Backup and Recovery

Database Backups

Set up automated backups:

# Manual backup
mysqldump -u user -p database_name > backup.sql

# Restore from backup
mysql -u user -p database_name < backup.sql

Image Backups

Generated images are stored in S3 (via Manus). Configure backup:

1. Enable S3 versioning
2. Set lifecycle policies for old objects
3. Test recovery procedures

---

Security Best Practices

1. Never commit secrets - Use environment variables only
2. Enable HTTPS - Hugging Face provides SSL by default
3. Rate limiting - Prevents abuse and API quota exhaustion
4. Input validation - All user inputs are sanitized
5. Database encryption - Use SSL for database connections
6. Regular updates - Keep dependencies updated

---

Troubleshooting

Application won't start

Check logs:

# In Hugging Face Logs tab, look for:
# - Database connection errors
# - Missing environment variables
# - Port binding issues

Solution:

1. Verify all required environment variables are set
2. Test database connection separately
3. Check Docker image build logs

Slow responses

Causes:

• Database queries too slow
• LLM model busy or overloaded
• Rate limiting triggered

Solutions:

1. Optimize database queries
2. Increase LLM fallback timeout
3. Upgrade Space compute

Memory leaks

Monitor:

• Check /api/health endpoint
• Monitor memory usage in logs

Fix:

1. Restart the Space
2. Review recent code changes
3. Increase available memory

---

Maintenance

Weekly Tasks

• Monitor error logs
• Check API quota usage
• Verify database backups

Monthly Tasks

• Review performance metrics
• Update dependencies
• Archive old conversations

Quarterly Tasks

• Security audit
• Database optimization
• Capacity planning

---

Support and Resources

• Documentation: See ARCHITECTURE.md and README.md
• NVIDIA API Docs: build.nvidia.com/docs
• Hugging Face Docs: huggingface.co/docs
• Issues: Check GitHub issues or contact support

---

Next Steps

1. Deploy to Hugging Face Spaces
2. Test all features (Ask, Imagine, Search)
3. Monitor logs for errors
4. Optimize based on usage patterns
5. Scale as needed

Good luck! 🚀