quantumtaskai-caprover/CAPROVER_DEPLOYMENT_GUIDE.md

CapRover Deployment Guide for Quantum Tasks AI

Overview

This guide provides step-by-step instructions for deploying the Quantum Tasks AI Django application on CapRover.

Prerequisites

• CapRover installed and running on your VPS
• Git repository with the Quantum Tasks AI project
• Basic understanding of Django and CapRover

---

Part 1: Project Files Overview

The project includes the following CapRover-specific files:

Required Files

quantum_render/
├── captain-definition          # CapRover configuration
├── Dockerfile.captain         # Production Docker configuration
├── .dockerignore              # Docker build optimization
├── requirements.txt           # Python dependencies (production-ready)
└── netcop_hub/settings.py     # Django settings with CapRover support

Key Configuration Features

• CapRover Auto-detection: Automatic host configuration via CAPROVER_GIT_COMMIT_SHA
• Database Flexibility: Supports SQLite (dev), PostgreSQL (production)
• Static Files: WhiteNoise configuration for production
• Security: Comprehensive security headers and middleware
• Environment Variables: Production-ready configuration

---

Part 2: Deploy PostgreSQL Database

2.1 Deploy PostgreSQL

1. CapRover Dashboard → Apps → One-Click Apps/Databases
2. Search: PostgreSQL
3. Configure:
   • App Name: quantum-ai-db
   • Version: 14.5 (recommended)
   • Username: quantum_user
   • Password: secure_password_123
   • Default Database: quantum_ai
4. Click Deploy

2.2 Note Connection Details

After deployment, note the internal hostname:

• Format: srv-captain--quantum-ai-db:5432
• Full URL: postgres://quantum_user:secure_password_123@srv-captain--quantum-ai-db:5432/quantum_ai

---

Part 3: Deploy Quantum Tasks AI Application

3.1 Create Django App

1. CapRover Dashboard → Apps → Create New App
2. App Name: quantum-tasks-ai
3. Check: "Has Persistent Data" (for media files)
4. Click: "Create New App"

3.2 Configure Git Deployment

1. Go to your app → Deployment tab
2. Select: "Method 3: Deploy from Github/Bitbucket/Gitlab"
3. Repository URL: https://github.com/yourusername/quantum_render.git
4. Branch: main
5. Click: "Save & Update"

3.3 Set Environment Variables

Go to: App Configs → Environment Variables

Required Variables:

SECRET_KEY=your-generated-secret-key
DEBUG=false
ALLOWED_HOSTS=quantum-tasks-ai.captain.your-domain.com
DATABASE_URL=postgres://quantum_user:secure_password_123@srv-captain--quantum-ai-db:5432/quantum_ai

# Email Configuration
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

# Stripe Configuration
STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

# AI API Keys
GROQ_API_KEY=your-groq-api-key
OPENAI_API_KEY=your-openai-api-key

# Webhook URLs for N8N integrations
N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n-instance.com/webhook/data-analyzer
N8N_WEBHOOK_FIVE_WHYS=https://your-n8n-instance.com/webhook/five-whys
N8N_WEBHOOK_JOB_POSTING=https://your-n8n-instance.com/webhook/job-posting
N8N_WEBHOOK_SOCIAL_ADS=https://your-n8n-instance.com/webhook/social-ads

# Optional: Redis for caching
REDIS_URL=redis://srv-captain--redis:6379/1

Generate SECRET_KEY:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

3.4 Deploy Application

1. Deployment tab → Force Build
2. Monitor logs for successful deployment

---

Part 4: Post-Deployment Setup

4.1 Install Portainer (For Container Management)

1. Apps → One-Click Apps → Search Portainer
2. Deploy with default settings
3. Access: https://portainer.captain.your-domain.com
4. Create admin account

4.2 Run Django Management Commands

Via Portainer Console:

1. Containers → Find your Django container
2. Console → /bin/bash → Connect
3. Run commands:

# Apply database migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Test the application
python manage.py check

# Collect static files (if needed)
python manage.py collectstatic --noinput

Via SSH (Alternative):

# SSH into your server
ssh root@your-server-ip

# Find container ID
docker ps | grep quantum-tasks-ai

# Run management commands
docker exec -it [container-id] python manage.py migrate
docker exec -it [container-id] python manage.py createsuperuser

4.3 Install pgAdmin (Database Management)

1. Apps → One-Click Apps → Search pgAdmin
2. Configure:
   • Email: admin@example.com
   • Password: secure_password
3. Deploy
4. Access: https://pgadmin.captain.your-domain.com

4.4 Connect pgAdmin to PostgreSQL

1. Login to pgAdmin
2. Add Server:
   • Name: Quantum AI DB
   • Host: srv-captain--quantum-ai-db
   • Port: 5432
   • Username: quantum_user
   • Password: secure_password_123

---

Part 5: Production Optimization

5.1 Enable HTTPS

1. Your app → HTTP Settings
2. Enable: Force HTTPS
3. Enable: Websocket Support (if needed)

5.2 Configure Custom Domain

1. Your app → HTTP Settings
2. Add: Custom Domain
3. Update ALLOWED_HOSTS environment variable

5.3 Set up Redis (Optional - For Performance)

1. Apps → One-Click Apps → Search Redis
2. Deploy with app name: quantum-ai-redis
3. Update environment variable: REDIS_URL=redis://srv-captain--quantum-ai-redis:6379/1

---

Part 6: Application-Specific Configuration

6.1 Agent System Configuration

The Quantum Tasks AI platform uses a file-based agent system with dual integrations:

Webhook Agents (N8N):

• Configure N8N webhook URLs in environment variables
• Test agent execution through the marketplace interface

Direct Access Agents:

• Configure external form URLs in agent JSON files
• Test payment flow and form redirection

6.2 Stripe Integration Setup

1. Configure Stripe webhook endpoint: https://your-domain.com/wallet/stripe/webhook/
2. Set webhook events:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • invoice.payment_succeeded
   • invoice.payment_failed

6.3 Email Verification Setup

1. Configure email settings in environment variables
2. Test email delivery from Django admin
3. Set REQUIRE_EMAIL_VERIFICATION=true for production

---

Part 7: Monitoring and Maintenance

7.1 Health Checks

The application includes built-in health monitoring:

• Health endpoint: /admin/ (requires authentication)
• Agent marketplace: /agents/ (public)
• API endpoints: /agents/api/ (for execution)

7.2 Log Management

Monitor application logs via:

• CapRover Dashboard: App logs
• Portainer: Container logs
• File logs: /app/logs/ in container

7.3 Database Backups

# Create backup
docker exec [postgres-container] pg_dump -U quantum_user quantum_ai > backup_$(date +%Y%m%d).sql

# Restore backup
docker exec -i [postgres-container] psql -U quantum_user quantum_ai < backup_file.sql

---

Part 8: Troubleshooting

8.1 Common Issues

Build Failures:

• Check Dockerfile.captain syntax
• Verify requirements.txt dependencies
• Check captain-definition format

Database Connection Errors:

• Verify DATABASE_URL format
• Check PostgreSQL container is running
• Confirm environment variables

Agent Execution Issues:

• Verify N8N webhook URLs
• Check API keys configuration
• Monitor execution logs in Django admin

Email Issues:

• Test SMTP configuration
• Check email credentials
• Verify firewall settings

8.2 Useful Commands

# Check container logs
docker logs [container-id]

# Database connection test
docker exec [container-id] python manage.py check_db

# Agent system test
docker exec [container-id] python manage.py shell -c "from agents.services import AgentFileService; print(AgentFileService.get_agent_stats())"

# Test webhooks
curl -X POST https://your-domain.com/agents/api/execute/ \
  -H "Content-Type: application/json" \
  -d '{"agent_slug": "test-agent", "form_data": {}}'

---

Security Best Practices

Environment Variables

• Never commit secrets to Git
• Use strong passwords for all services
• Rotate SECRET_KEY regularly
• Use separate API keys for production

Database Security

• Use specific database users per app
• Restrict database permissions
• Enable connection encryption
• Regular backups

Application Security

• Keep Django updated
• Use HTTPS in production
• Configure proper ALLOWED_HOSTS
• Monitor security logs

---

Quick Reference

Essential URLs

• CapRover: https://captain.your-domain.com
• Quantum Tasks AI: https://quantum-tasks-ai.captain.your-domain.com
• Portainer: https://portainer.captain.your-domain.com
• pgAdmin: https://pgadmin.captain.your-domain.com

Key Management Commands

# Django management
python manage.py migrate
python manage.py collectstatic
python manage.py createsuperuser
python manage.py check_db

# Agent system
python manage.py shell -c "from agents.services import AgentFileService; print('Agents:', AgentFileService.list_agents())"

# Docker
docker ps
docker logs [container-id]
docker exec -it [container-id] /bin/bash

This guide provides a complete deployment process for the Quantum Tasks AI platform on CapRover, taking advantage of the application's production-ready configuration and dual agent integration system.