InstaFuel_Chatbot_public/report.md

InstaFuel Chatbot Deployment Guide

Executive Summary

This guide provides comprehensive deployment instructions for the InstaFuel Multi-Agent Chatbot - a hybrid Python FastAPI backend with React TypeScript frontend designed for e-commerce fitness supplement brands. The system uses Google Gemini AI, Qdrant vector database, and DuckDB for conversation persistence.

---

Table of Contents

1. Architecture Overview
2. Prerequisites
3. Environment Configuration
4. Deployment Options
5. Production Deployment
6. Database Deployment
7. Monitoring Setup
8. Frontend Deployment
9. Troubleshooting
10. Security Best Practices

---

Architecture Overview

System Components

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  React Frontend │────▶│  FastAPI Backend │────▶│  Google Gemini  │
│   (Port 5173)   │     │   (Port 8000)    │     │     (LLM)       │
└─────────────────┘     └────────┬─────────┘     └─────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        ▼                        ▼                        ▼
┌───────────────┐      ┌─────────────────┐      ┌─────────────────┐
│    Qdrant     │      │     DuckDB      │      │     Redis       │
│ (Vector DB)   │      │  (Chat Store)   │      │    (Cache)      │
│  (Port 6333)  │      │                 │      │  (Port 6379)    │
└───────────────┘      └─────────────────┘      └─────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Monitoring Stack                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │  Prometheus  │  │   Grafana    │  │   Application Logs   │   │
│  │  (Port 9090) │  │  (Port 3000) │  │     (./logs)         │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	React 18 + TypeScript + Vite	User interface
Backend	Python 3.11 + FastAPI	REST API server
LLM	Google Gemini / OpenRouter	Conversational AI
Vector DB	Qdrant	Product embeddings
Structured DB	DuckDB	Conversation history
Cache	Redis	Session caching
Monitoring	Prometheus + Grafana	Metrics & dashboards
Containerization	Docker + Docker Compose	Deployment orchestration

---

Prerequisites

Required Software

# Check Docker installation
docker --version  # Requires Docker 20.10+

# Check Docker Compose
docker-compose --version  # OR
docker compose version    # Docker Compose v2+

# For local development (optional)
python3.11 --version      # Python 3.11+
node --version            # Node.js 18+
npm --version             # npm 9+

API Keys Required

Before deployment, you must obtain:

1. Google Gemini API Key (Get here)
2. OpenRouter API Key (optional, for model fallback)
3. Qdrant Cloud API Key (if using managed Qdrant)
4. E-commerce API credentials (your store's API)
5. CRM API credentials (optional)

---

Environment Configuration

1. Create Environment File

cp .env.example .env

2. Required Environment Variables

Core AI Configuration

# Primary LLM Provider
MODEL_PROVIDER=openrouter          # Options: openrouter, gemini
MODEL_NAME=meta-llama/llama-3.1-70b-instruct
GEMINI_API_KEY=your_gemini_api_key
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

# OpenRouter Configuration (if using MODEL_PROVIDER=openrouter)
OPENROUTER_API_KEY=your_openrouter_key

Database Configuration

# DuckDB Chat Store (choose one)
# Option A: Local file
CHAT_STORE_PATH=data/chat_store.duckdb

# Option B: MotherDuck Cloud
CHAT_STORE_PATH=md:instafuel_prod
MOTHERDUCK_TOKEN=your_motherduck_token

# Option C: AWS S3
CHAT_STORE_PATH=s3://my-bucket/instafuel/chat.duckdb
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1

# Option D: EFS/NFS (multi-server)
CHAT_STORE_PATH=/mnt/efs/instafuel/chat_store.duckdb

# Redis (for caching)
REDIS_URL=redis://localhost:6379/0

Vector Database (Qdrant)

# Local Qdrant (default)
QDRANT_HOST=localhost
QDRANT_PORT=6333

# Cloud Qdrant
QDRANT_URL=https://your-cluster.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key

Embeddings Configuration

# Option A: Local Ollama (recommended for privacy)
EMBED_BASE_URL=http://127.0.0.1:11434/v1
EMBED_API_KEY=ollama

# Option B: OpenRouter embeddings
EMBED_BASE_URL=https://openrouter.ai/api/v1
EMBED_API_KEY=your_openrouter_key

External API Integration

# E-commerce Platform
ECOMMERCE_API_URL=https://api.yourstore.com/v1
ECOMMERCE_API_KEY=your_ecommerce_api_key

# CRM Integration (optional)
CRM_API_URL=https://api.yourcrm.com/v1
CRM_API_KEY=your_crm_api_key

Application Settings

ENVIRONMENT=production
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# Agent Configuration
MAX_CONTEXT_TURNS=10
CONVERSATION_TIMEOUT=1800
FALLBACK_TO_HUMAN_THRESHOLD=3

# Analytics
ANALYTICS_RETENTION_DAYS=90
METRICS_COLLECTION_INTERVAL=300

Social Platform Integration (Optional)

# WhatsApp Business API
WHATSAPP_TOKEN=your_whatsapp_token
WHATSAPP_VERIFY_TOKEN=your_verify_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id

# Instagram Graph API
INSTAGRAM_ACCESS_TOKEN=your_instagram_token
INSTAGRAM_APP_SECRET=your_app_secret

---

Deployment Options

Option 1: Docker Compose (Recommended for Production)

This is the simplest production deployment method using the provided deploy.sh script.

Step 1: Prepare Environment

# Clone/navigate to repository
cd InstaFuel_Chatbot

# Make deploy script executable
chmod +x deploy.sh

# Create environment file
cp .env.example .env
# Edit .env with your API keys
nano .env

Step 2: Run Deployment Script

./deploy.sh

This script will:

1. Validate Docker and Docker Compose installation
2. Create required directories (logs, monitoring/)
3. Generate Prometheus and Grafana configurations
4. Build the chatbot Docker image
5. Start all services (chatbot, Redis, Prometheus, Grafana)

Step 3: Verify Deployment

# Check all services are running
docker-compose ps

# View logs
docker-compose logs -f chatbot

# Test health endpoint
curl http://localhost:8000/health
# Expected: {"status":"ok"}

# Test chat endpoint
curl -X POST http://localhost:8000/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello, what supplements do you recommend?","user_id":"test"}'

Access Points

Service	URL	Credentials
Chatbot API	http://localhost:8000	-
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3000	admin/admin
Redis	localhost:6379	-

Stopping Services

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: deletes data)
docker-compose down -v

---

Option 2: Kubernetes Deployment

For high-availability production deployments.

Prerequisites

# Install kubectl
kubectl version --client

# Set up cluster (example with EKS)
aws eks update-kubeconfig --region us-east-1 --name instafuel-cluster

Step 1: Create ConfigMap

# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: chatbot-config
data:
  MODEL_PROVIDER: "openrouter"
  MODEL_NAME: "meta-llama/llama-3.1-70b-instruct"
  CHAT_STORE_PATH: "md:instafuel_prod"
  QDRANT_URL: "https://your-cluster.qdrant.io"
  ENVIRONMENT: "production"
  API_HOST: "0.0.0.0"
  API_PORT: "8000"
  LOG_LEVEL: "INFO"

Step 2: Create Secret

# Create secret for sensitive data
kubectl create secret generic chatbot-secrets \
  --from-literal=GEMINI_API_KEY=your_key \
  --from-literal=OPENROUTER_API_KEY=your_key \
  --from-literal=QDRANT_API_KEY=your_key \
  --from-literal=MOTHERDUCK_TOKEN=your_token

Step 3: Deployment YAML

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: instafuel-chatbot
  labels:
    app: chatbot
spec:
  replicas: 3
  selector:
    matchLabels:
      app: chatbot
  template:
    metadata:
      labels:
        app: chatbot
    spec:
      containers:
      - name: chatbot
        image: instafuel/chatbot:latest
        ports:
        - containerPort: 8000
        envFrom:
        - configMapRef:
            name: chatbot-config
        - secretRef:
            name: chatbot-secrets
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: chatbot-service
spec:
  selector:
    app: chatbot
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Step 4: Deploy

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml

# Verify deployment
kubectl get pods
kubectl get svc

---

Option 3: AWS ECS/Fargate

For serverless container deployment.

Step 1: Build and Push Image

# Build image
docker build -t instafuel/chatbot:latest .

# Tag for ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account.dkr.ecr.us-east-1.amazonaws.com
docker tag instafuel/chatbot:latest your-account.dkr.ecr.us-east-1.amazonaws.com/instafuel/chatbot:latest
docker push your-account.dkr.ecr.us-east-1.amazonaws.com/instafuel/chatbot:latest

Step 2: Create ECS Task Definition

{
  "family": "instafuel-chatbot",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "executionRoleArn": "arn:aws:iam::your-account:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "chatbot",
      "image": "your-account.dkr.ecr.us-east-1.amazonaws.com/instafuel/chatbot:latest",
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "ENVIRONMENT", "value": "production"},
        {"name": "MODEL_PROVIDER", "value": "openrouter"},
        {"name": "MODEL_NAME", "value": "meta-llama/llama-3.1-70b-instruct"}
      ],
      "secrets": [
        {"name": "GEMINI_API_KEY", "valueFrom": "arn:aws:secretsmanager:..."},
        {"name": "OPENROUTER_API_KEY", "valueFrom": "arn:aws:secretsmanager:..."}
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/instafuel-chatbot",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

Step 3: Deploy via AWS CLI

# Register task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json

# Create service
aws ecs create-service \
  --cluster instafuel-cluster \
  --service-name chatbot-service \
  --task-definition instafuel-chatbot:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"

---

Option 4: Google Cloud Run

For fully managed serverless deployment.

# Build and push to Google Container Registry
gcloud builds submit --tag gcr.io/your-project/instafuel-chatbot

# Deploy to Cloud Run
gcloud run deploy instafuel-chatbot \
  --image gcr.io/your-project/instafuel-chatbot \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "ENVIRONMENT=production" \
  --set-env-vars "MODEL_PROVIDER=openrouter" \
  --set-secrets "GEMINI_API_KEY=gemini-api-key:latest,OPENROUTER_API_KEY=openrouter-key:latest"

---

Database Deployment

The DuckDB chat store supports multiple deployment configurations:

Option A: Local File (Development/Single Server)

Best for: Development, testing, single-server deployments

CHAT_STORE_PATH=data/chat_store.duckdb

Pros: Simple setup, fast local access, no external dependencies Cons: Not suitable for multi-server deployments, no automatic backups

Option B: MotherDuck Cloud (Recommended for Production)

Best for: Production deployments requiring high availability

CHAT_STORE_PATH=md:instafuel_prod
MOTHERDUCK_TOKEN=your_motherduck_token

Setup Steps:

1. Sign up at motherduck.com
2. Create a database via the MotherDuck console
3. Generate an API token from settings
4. Set environment variables

Pros: Fully managed, automatic backups, multi-region support Cons: Requires internet connectivity, additional service cost

Option C: Amazon S3

Best for: Cost-effective storage for large datasets

CHAT_STORE_PATH=s3://my-instafuel-bucket/chat/chat_store.duckdb
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

IAM Policy Required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::my-instafuel-bucket/chat/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-instafuel-bucket"
    }
  ]
}

Option D: AWS EFS/NFS (Multi-Server)

Best for: Multi-server deployments with shared storage

CHAT_STORE_PATH=/mnt/efs/instafuel/chat_store.duckdb

Setup Steps:

# Mount EFS on EC2 instances
sudo mount -t nfs4 -o nfsvers=4.1 \
  fs-12345678.efs.us-east-1.amazonaws.com:/ /mnt/efs

# Set permissions
sudo chown -R app_user:app_user /mnt/efs
sudo chmod 755 /mnt/efs

Database Migration

# Export from Local to MotherDuck
import duckdb

local = duckdb.connect("data/chat_store.duckdb")
remote = duckdb.connect("md:instafuel_prod?motherduck_token=TOKEN")

# Copy tables
local.execute("ATTACH 'md:instafuel_prod?motherduck_token=TOKEN' AS remote")
local.execute("CREATE TABLE remote.conversations AS SELECT * FROM conversations")
local.execute("CREATE TABLE remote.messages AS SELECT * FROM messages")
local.execute("CREATE TABLE remote.user_context AS SELECT * FROM user_context")

---

Monitoring Setup

Prometheus Configuration

The deployment script automatically creates monitoring/prometheus.yml:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'chatbot'
    static_configs:
      - targets: ['chatbot:8000']
    metrics_path: '/metrics'
    scrape_interval: 5s

Grafana Configuration

Datasources (auto-configured):

• Prometheus: http://prometheus:9090

Default Dashboards:

• Request latency and throughput
• Error rates
• LLM token usage
• Conversation metrics

Access: http://localhost:3000 (admin/admin)

Custom Metrics

The application exposes these Prometheus metrics:

# Available at /metrics endpoint
# - http_requests_total: Total HTTP requests
# - http_request_duration_seconds: Request latency
# - llm_tokens_total: Total LLM tokens consumed
# - conversations_active: Number of active conversations
# - response_time_seconds: Chat response generation time

---

Frontend Deployment

Development Mode

cd frontend
npm install
npm run dev
# Access: http://localhost:5173

Production Build

cd frontend
npm install
npm run build
# Output: frontend/dist/

Deploy to Static Hosting

Option 1: Vercel

cd frontend
npm i -g vercel
vercel --prod

Option 2: Netlify

cd frontend
npm run build
netlify deploy --prod --dir=dist

Option 3: AWS S3 + CloudFront

# Sync to S3
aws s3 sync frontend/dist s3://instafuel-frontend-bucket --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation --distribution-id YOUR_DIST_ID --paths "/*"

Environment Variables (Frontend)

Create frontend/.env:

VITE_API_BASE_URL=https://api.instafuel.ai
VITE_WS_URL=wss://api.instafuel.ai

---

Troubleshooting

Common Issues

Issue: "Failed to connect to DuckDB"

Local File:

• Check file permissions and disk space
• Ensure directory exists: mkdir -p data

MotherDuck:

• Verify token is valid and not expired
• Check internet connectivity

S3:

• Verify AWS credentials and bucket permissions
• Ensure bucket exists and is in correct region

EFS:

• Verify mount point exists: ls /mnt/efs
• Check NFS service is running

Issue: "Conversation ID does not belong to user"

• This is application-level validation
• Ensure user_id and conversation_id pair matches
• Check client is sending correct IDs from previous response

Issue: Slow queries on S3

• DuckDB caches S3 data locally; first query is always slower
• Consider using MotherDuck for production if latency matters
• Increase local disk space for better caching

Issue: EFS mount issues

# Check security group allows NFS (port 2049)
# Verify mount targets exist in your subnet
# Test mount:
sudo mount -t nfs4 -o nfsvers=4.1 fs-xxx.efs.us-east-1.amazonaws.com:/ /mnt/efs

Issue: Container fails to start

# Check logs
docker-compose logs -f chatbot

# Common causes:
# 1. Missing .env file
# 2. Invalid API keys
# 3. Qdrant not accessible
# 4. Port conflicts (8000, 6379, 9090, 3000)

Debug Commands

# Test API directly
curl -X POST http://localhost:8000/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"test","user_id":"debug"}'

# Check Qdrant connection
curl http://localhost:6333/collections

# Check Redis connection
redis-cli ping

# View all logs
docker-compose logs -f

# Shell into container
docker-compose exec chatbot /bin/bash

---

Security Best Practices

1. API Key Management

# Never commit .env file
echo ".env" >> .gitignore

# Use secret management in production:
# - AWS Secrets Manager
# - Google Secret Manager
# - HashiCorp Vault
# - Kubernetes Secrets

2. Encryption at Rest

Service	Configuration
S3	Enable default encryption (SSE-S3 or SSE-KMS)
EFS	Enable encryption at rest during creation
MotherDuck	Encrypted by default
Local	Use encrypted volumes

3. Network Security

# EFS: Use VPC security groups
# S3: Use VPC endpoints
# MotherDuck: Uses TLS 1.3
# API: Always use HTTPS in production

4. Access Control

# S3: Use IAM roles, not access keys
# EFS: Use POSIX permissions and security groups
# MotherDuck: Use token rotation policies
# API: Implement rate limiting

5. Rate Limiting

# Add to FastAPI (requires slowapi package)
from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@app.post("/chat")
@limiter.limit("10/minute")
async def chat(request: Request, payload: ChatRequest):
    ...

---

Performance Considerations

Database Performance

Storage Type	Read Latency	Write Latency	Concurrent Users
Local File	<1ms	1-5ms	Limited by disk I/O
MotherDuck	50-200ms (first), <10ms (cached)	100-300ms	Thousands
S3	100-500ms	200-1000ms	Unlimited
EFS	5-50ms	10-100ms	Hundreds

Scaling Recommendations

Small Scale (<1000 daily users):

• Single Docker Compose deployment
• Local DuckDB file
• Redis container

Medium Scale (1000-10000 daily users):

• Kubernetes with 2-3 replicas
• MotherDuck for chat store
• Managed Redis (AWS ElastiCache)

Large Scale (10000+ daily users):

• Kubernetes with auto-scaling
• MotherDuck multi-region
• Separate read replicas
• CDN for frontend

---

Maintenance

Backup Strategy

# Daily backup from MotherDuck to S3
python << 'EOF'
import duckdb
conn = duckdb.connect("md:instafuel_prod?motherduck_token=TOKEN")
conn.execute("COPY (SELECT * FROM conversations) TO 's3://backup-bucket/conversations.parquet'")
conn.execute("COPY (SELECT * FROM messages) TO 's3://backup-bucket/messages.parquet'")
EOF

# Schedule with cron (daily at 2 AM)
0 2 * * * /usr/local/bin/python /path/to/backup.py

Log Rotation

# Docker Compose handles this automatically
# For manual setup, configure logrotate
/etc/logrotate.d/instafuel-chatbot:
/path/to/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 user user
}

Updates

# Pull latest code
git pull origin main

# Rebuild and deploy
./deploy.sh

# Or for zero-downtime with Kubernetes
kubectl set image deployment/chatbot chatbot=instafuel/chatbot:v2.0

---

Support

For deployment assistance:

1. Check logs: docker-compose logs -f chatbot
2. Review documentation in docs/ directory
3. Run smoke tests: python scripts/smoke_test.py
4. Contact your DevOps team with logs and configuration

---

Document Version: 1.0 Last Updated: 2026-02-12 Maintained by: InstaFuel Engineering Team