# 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

```bash
# 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)

```bash
# 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)

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

```env
# 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

- **Frontend (Setup Wizard)**: http://localhost:3000
- **API**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs
- **Health Check**: http://localhost:8000/health
- **Setup Status**: http://localhost:8000/api/setup/status

### Production (with Domain)

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

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

```bash
# Edit .env file directly
vi .env

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

---

## 📊 Monitoring and Management

### Check Service Status

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

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

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

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

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

```bash
# 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
- [Main Documentation](README.md)
- [Security Guide](SECURITY.md)
- [Deployment Guide](DEPLOYMENT.md)
- [API Documentation](http://localhost:8000/docs)

### 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!