Skip to content

SAAS_DEPLOYMENT.md

Latest commit

 

History

History
523 lines (388 loc) · 11.7 KB

SAAS_DEPLOYMENT.md

File metadata and controls

523 lines (388 loc) · 11.7 KB
Raw

DataTruth - SaaS Deployment Guide

🚀 Ship and Go - One-Command Deployment

DataTruth now features a beautiful web-based setup wizard that eliminates manual configuration. Just deploy with Docker and configure everything through your browser!

⚡ Quick Start (3 Steps)

1. Clone and Deploy

# Clone repository
git clone <your-repo-url>
cd datatruth

# Start with Docker Compose
docker-compose -f docker-compose.saas.yml up -d

That's it! No .env file editing, no manual configuration needed.

2. Open Setup Wizard

Visit http://localhost:3000 in your browser. You'll see the setup wizard automatically.

3. Follow the Wizard

The wizard will guide you through:

  • ✅ Database Configuration - PostgreSQL connection details
  • ✅ OpenAI Integration - Your API key and model selection
  • ✅ Admin Account - Create your administrator login
  • ✅ Review & Deploy - Verify and complete setup

Done! Your application will restart and you'll be redirected to the login page.

🎨 Setup Wizard Features

Step 1: Welcome

  • Overview of setup process
  • What you'll need (Database, OpenAI key, Admin credentials)
  • Beautiful, intuitive interface

Step 2: Database Configuration

  • Host: postgres (for Docker) or your PostgreSQL server
  • Port: 5432 (default)
  • Database Name: datatruth_internal
  • User Credentials: App user and admin passwords
  • Test Connection: Verify database connectivity before proceeding
  • Auto-Detection: Shows PostgreSQL version and database status

Step 3: OpenAI Configuration

  • API Key: Your OpenAI API key (starts with sk-)
  • Model Selection:
    • gpt-4o-mini (Recommended - cost-effective)
    • gpt-4o (Most capable)
    • gpt-4-turbo (Fast and powerful)
    • gpt-3.5-turbo (Budget option)
  • Temperature: Adjust creativity (0.0 = precise, 2.0 = creative)
  • Test Connection: Validates API key and model access

Step 4: Admin Account

  • Username: Your admin username (default: admin)
  • Password: Strong password (min 8 chars, uppercase, lowercase, numbers)
  • Email: Optional admin email
  • Full Name: Optional display name
  • Password Validation: Real-time validation of password strength

Step 5: Review & Complete

  • Review Configuration: See all your settings before submitting
  • One-Click Deploy: Initialize database, create admin, save config
  • Auto-Restart: Application restarts with new configuration
  • Redirect: Automatically redirects to login page

🐳 Docker Deployment Options

Option 1: SaaS Mode (Recommended)

# Simple deployment with setup wizard
docker-compose -f docker-compose.saas.yml up -d

# Access setup wizard
open http://localhost:3000

Includes:

  • PostgreSQL 16
  • Redis 7
  • FastAPI Backend (4 workers)
  • React Frontend
  • Setup wizard enabled
  • Auto-configuration

Option 2: Production Mode (Pre-configured)

# Traditional deployment with .env file
cp .env.production .env
vi .env  # Edit configuration

# Deploy
docker-compose -f docker-compose.prod.yml up -d

Includes:

  • All services from SaaS mode
  • Nginx reverse proxy
  • SSL/TLS support
  • Production optimizations
  • Manual configuration required

🔧 Configuration Details

What Gets Configured

The setup wizard creates:

  1. .env file - All environment variables
  2. data/setup.json - Setup configuration backup
  3. data/.setup_complete - Setup completion marker
  4. Database schema - All tables, indexes, triggers
  5. Admin user - Your administrator account
  6. Security keys - Auto-generated SECRET_KEY and JWT_SECRET_KEY

Generated Configuration

# Application
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=INFO
APP_NAME=DataTruth

# Database (from wizard)
INTERNAL_DB_HOST=postgres
INTERNAL_DB_PORT=5432
INTERNAL_DB_NAME=datatruth_internal
INTERNAL_DB_USER=datatruth_app
INTERNAL_DB_PASSWORD=<your-password>
INTERNAL_DB_ADMIN_USER=datatruth_admin
INTERNAL_DB_ADMIN_PASSWORD=<your-admin-password>

# Security (auto-generated)
SECRET_KEY=<auto-generated-32-chars>
JWT_SECRET_KEY=<auto-generated-32-chars>
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60

# OpenAI (from wizard)
OPENAI_API_KEY=sk-<your-key>
OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.7

# Features (enabled by default)
ENABLE_USER_ACTIVITY_TRACKING=true
ENABLE_PERSONALIZED_SUGGESTIONS=true
ENABLE_CALCULATED_METRICS=true
ENABLE_INSIGHTS=true

📋 System Requirements

Minimum

  • Docker: 20.10+
  • Docker Compose: 2.0+
  • RAM: 4GB
  • CPU: 2 cores
  • Disk: 10GB
  • OpenAI API Key: Required

Recommended

  • RAM: 8GB+
  • CPU: 4+ cores
  • Disk: 50GB SSD
  • Network: Stable internet connection

🌐 Accessing Your Application

Local Development

Production (with Domain)

# Configure your domain
# Update CORS_ORIGINS and ALLOWED_HOSTS in .env

# Access via domain
https://yourdomain.com

🔐 Security Best Practices

During Setup

  1. Strong Passwords

    • Use 12+ characters
    • Mix uppercase, lowercase, numbers, symbols
    • Don't reuse passwords

  2. OpenAI API Key

    • Keep it secret
    • Use environment variables
    • Rotate regularly

  3. Database Credentials

    • Different passwords for app user and admin
    • Store securely
    • Limit network access

After Setup

  1. Change Default Settings

    • Review generated configuration
    • Update CORS origins for your domain
    • Configure SSL/TLS for production

  2. Backup Configuration

    # Backup setup configuration
cp data/setup.json backups/setup-$(date +%Y%m%d).json
cp .env backups/env-$(date +%Y%m%d)

  3. Enable HTTPS

    • Obtain SSL certificate
    • Configure Nginx
    • Redirect HTTP to HTTPS

🔄 Re-running Setup

Reset and Reconfigure

If you need to change configuration:

# Stop services
docker-compose -f docker-compose.saas.yml down

# Remove setup markers
rm data/.setup_complete
rm data/setup.json
rm .env

# Restart
docker-compose -f docker-compose.saas.yml up -d

# Visit http://localhost:3000 again

Modify Existing Configuration

# Edit .env file directly
vi .env

# Restart services
docker-compose -f docker-compose.saas.yml restart api

📊 Monitoring and Management

Check Service Status

# View all containers
docker-compose -f docker-compose.saas.yml ps

# View logs
docker-compose -f docker-compose.saas.yml logs -f api

# Check health
curl http://localhost:8000/health

Access Database

# Connect to PostgreSQL
docker-compose -f docker-compose.saas.yml exec postgres \
  psql -U datatruth_app -d datatruth_internal

# View users
SELECT username, role, email FROM users;

Backup Database

# Create backup
docker-compose -f docker-compose.saas.yml exec postgres \
  pg_dump -U datatruth_admin datatruth_internal | gzip > backup.sql.gz

🐛 Troubleshooting

Setup Wizard Not Loading

# Check frontend logs
docker-compose -f docker-compose.saas.yml logs frontend

# Check API logs
docker-compose -f docker-compose.saas.yml logs api

# Ensure services are running
docker-compose -f docker-compose.saas.yml ps

Database Connection Failed

Error: "Database connection failed"

Solutions:

  1. Ensure PostgreSQL container is running
  2. Check database credentials
  3. Verify network connectivity
  4. Use postgres as host in Docker
  5. Check PostgreSQL logs: 
    docker-compose -f docker-compose.saas.yml logs postgres

OpenAI API Key Invalid

Error: "Invalid API key"

Solutions:

  1. Verify key starts with sk-
  2. Check key hasn't expired
  3. Ensure you have API credits
  4. Test key at https://platform.openai.com
  5. Try a different model

Setup Stuck or Failed

# Check setup status
curl http://localhost:8000/api/setup/status

# View API logs for errors
docker-compose -f docker-compose.saas.yml logs api | grep ERROR

# Restart and retry
docker-compose -f docker-compose.saas.yml restart api

Port Already in Use

Error: "Port 3000 (or 8000) is already allocated"

Solutions:

# Find process using port
lsof -i :3000
lsof -i :8000

# Kill process
kill -9 <PID>

# Or change port in docker-compose.saas.yml
# Change "3000:3000" to "3001:3000"

🚀 Production Deployment

Cloud Platforms

AWS

# Using EC2
1. Launch EC2 instance (Ubuntu 22.04, t3.medium)
2. Install Docker and Docker Compose
3. Clone repository
4. Run: docker-compose -f docker-compose.saas.yml up -d
5. Configure security group (ports 80, 443, 3000, 8000)
6. Access via public IP or domain

Google Cloud

# Using Compute Engine
1. Create VM instance (Ubuntu, e2-standard-2)
2. Install Docker and Docker Compose
3. Clone repository
4. Run: docker-compose -f docker-compose.saas.yml up -d
5. Configure firewall rules
6. Access via external IP or domain

Azure

# Using Azure Container Instances
1. Create Container Instance
2. Deploy with docker-compose.saas.yml
3. Configure DNS label
4. Access via FQDN

Domain and SSL

# 1. Point domain to your server
# 2. Install Certbot
sudo apt-get install certbot

# 3. Obtain SSL certificate
sudo certbot certonly --standalone -d yourdomain.com

# 4. Update docker-compose.saas.yml
# Enable nginx with production profile:
docker-compose -f docker-compose.saas.yml --profile production up -d

# 5. Configure nginx with SSL
# Edit nginx/nginx.conf with certificate paths

📦 What's Included

Backend (Python/FastAPI)

  • ✅ Natural language query processing
  • ✅ Semantic layer with metrics and dimensions
  • ✅ Database connection management
  • ✅ AI-powered field mapping
  • ✅ User activity tracking
  • ✅ Personalized suggestions
  • ✅ Health monitoring
  • ✅ API documentation (Swagger/ReDoc)

Frontend (React/TypeScript)

  • ✅ Beautiful setup wizard
  • ✅ Modern UI with Tailwind CSS
  • ✅ Real-time connection testing
  • ✅ Password validation
  • ✅ Progress tracking
  • ✅ Responsive design
  • ✅ Error handling

Infrastructure

  • ✅ PostgreSQL 16 (database)
  • ✅ Redis 7 (cache)
  • ✅ Nginx (reverse proxy, optional)
  • ✅ Docker Compose orchestration
  • ✅ Health checks
  • ✅ Auto-restart policies

💡 Next Steps After Setup

  1. Login with your admin credentials
  2. Add Database Connections to your data sources
  3. Create Calculated Metrics for your business KPIs
  4. Start Querying with natural language
  5. Invite Team Members to collaborate
  6. Explore Insights for automated analytics
  7. Customize semantic layer for your domain

🆘 Support

Documentation

Common Issues

  • Check logs: docker-compose logs -f api
  • Verify setup: curl http://localhost:8000/api/setup/status
  • Test health: curl http://localhost:8000/health
  • Reset setup: Remove data/.setup_complete and restart

Getting Help

  • GitHub Issues: Report bugs and feature requests
  • Email: support@datatruth.com (configure for your org)
  • Documentation: See docs/ directory

🎉 Success!

You now have a fully functional DataTruth instance running with:

  • ✅ Web-based configuration (no manual editing!)
  • ✅ Secure authentication
  • ✅ AI-powered analytics
  • ✅ Beautiful interface
  • ✅ Production-ready infrastructure

Start querying your data with natural language! 🚀

DataTruth - Shipped as a complete SaaS product. Deploy once, configure via web, and start analyzing!