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](https://huggingface.co)
2. **NVIDIA API Key** - Get from [NVIDIA API Portal](https://build.nvidia.com/)
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](https://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:

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

Initialize a Git repository and push to Hugging Face:

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

```bash
# 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](https://build.nvidia.com/)
  - 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:

```bash
# 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:**
```bash
# 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](https://build.nvidia.com/docs)
- **Hugging Face Docs**: [huggingface.co/docs](https://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! 🚀