1 line
15 KiB
JSON
1 line
15 KiB
JSON
{"repo": "adamkrysztopa/statmate-ai", "files": {"docs/setup/DEV_VS_PROD_GUIDE.md": {"98d9ed440aed90ad6ecfca020f276b55f1189e5f": {"t": 1785747180.8451207, "n": 12605, "h": "0763e77b1d92e145", "c": "# Development vs Production Mode Guide\n\n## Overview\n\nStatmateAI supports two distinct operating modes to handle AI model credentials securely:\n\n- **Development Mode** 🔧 - API keys stored in `.env` file (never committed to git)\n- **Production Mode** 🚀 - Users provide their own credentials through the UI\n\nThis guide explains how to use each mode and why this separation is important.\n\n---\n\n## 🔒 Security First\n\n### Why Two Modes?\n\n**The Problem:**\n- API keys are sensitive credentials that should NEVER be committed to git\n- Sharing `.env` files is insecure\n- Production users should provide their own keys, not use shared credentials\n\n**The Solution:**\n- **DEV Mode**: Developers use their own API keys from `.env` (git-ignored)\n- **PROD Mode**: End users enter credentials through a secure UI form\n\n---\n\n## 🔧 Development Mode\n\n### What is it?\n\nDevelopment mode is for local development and testing. API keys are loaded from the `.env` file.\n\n### When to use it?\n\n- Local development on your machine\n- Testing new features\n- Running the app for personal use\n- Contributing to the project\n\n### Setup\n\n#### 1. Create `.env` file\n\n```bash\n# Quick setup\nmake setup-env\n\n# Or manually\ncp .env.example .env\n```\n\n#### 2. Add your API keys to `.env`\n\n```ini\n# Required: At least one provider\nOPENAI_API_KEY=sk-proj-...your-key-here...\n\n# Optional: Additional providers\nANTHROPIC_API_KEY=sk-ant-...\nGOOGLE_API_KEY=AI...\nGROQ_API_KEY=gsk_...\n\n# Optional: Local models (FREE!)\nOLLAMA_ENABLED=true\nOLLAMA_DEFAULT_MODEL=deepseek-r1:8b\n```\n\n#### 3. Set environment to development\n\n```ini\nENVIRONMENT=development\nDEBUG=true\n```\n\n#### 4. Run the application\n\n```bash\n# Easy way\nmake dev\n\n# Or manual way\npython statmate/api/main.py # Terminal 1\nstreamlit run statmate/ui/app.py # Terminal 2\n```\n\n### What happens in DEV mode?\n\n```\n┌─────────────────────────────────────┐\n│ .env file (git-ignored) │\n│ ├─ OPENAI_API_KEY=sk-... │\n│ ├─ ANTHROPIC_API_KEY=sk-ant-... │\n│ └─ ENVIRONMENT=development │\n└─────────────┬───────────────────────┘\n │ (loaded at startup)\n ▼\n┌─────────────────────────────────────┐\n│ FastAPI Backend │\n│ ├─ Loads credentials from .env │\n│ ├─ Initializes model factory │\n│ └─ Ready to analyze data │\n└─────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────┐\n│ Streamlit UI │\n│ ├─ Shows \"DEV MODE\" banner │\n│ ├─ No credential input required │\n│ └─ Ready to use │\n└─────────────────────────────────────┘\n```\n\n### UI Indicators\n\nWhen running in DEV mode, you'll see:\n- 🔧 **DEV MODE** - Using credentials from .env file\n\n---\n\n## 🚀 Production Mode\n\n### What is it?\n\nProduction mode is for deploying the app for end users. Users must provide their own API credentials through the UI.\n\n### When to use it?\n\n- Deploying to a server for multiple users\n- Sharing the app with non-technical users\n- Running in a cloud environment\n- When each user should use their own API quota\n\n### Setup\n\n#### 1. Set environment to production\n\n```bash\n# Option 1: Environment variable\nexport ENVIRONMENT=production\n\n# Option 2: In .env file (but don't include API keys!)\necho \"ENVIRONMENT=production\" > .env\necho \"DEBUG=false\" >> .env\n```\n\n#### 2. Do NOT include API keys in `.env`\n\n```ini\n# .env file for PROD (minimal)\nENVIRONMENT=production\nDEBUG=false\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\nDATABASE_URL=postgresql://... # Use PostgreSQL in prod\nSECRET_KEY=your-secure-random-key\n```\n\n#### 3. Run in production mode\n\n```bash\n# Using Makefile\nmake prod\n\n# Or manually\nexport ENVIRONMENT=production\npython statmate/api/main.py &\nstreamlit run statmate/ui/app.py\n```\n\n### What happens in PROD mode?\n\n```\n┌─────────────────────────────────────┐\n│ User opens Streamlit UI │\n└─────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────┐\n│ Credential Setup Page │\n│ ┌───────────────────────────────┐ │\n│ │ Please provide your API keys │ │\n│ │ │ │\n│ │ OpenAI: [.................] │ │\n│ │ Anthropic: [...............] │ │\n│ │ Google: [..................] │ │\n│ │ Groq: [...................] │ │\n│ │ Ollama: [☐] Enable │ │\n│ │ │ │\n│ │ [Configure & Start] │ │\n│ └───────────────────────────────┘ │\n└─────────────┬───────────────────────┘\n │ (POST /api/v1/models/credentials)\n ▼\n┌─────────────────────────────────────┐\n│ FastAPI Backend │\n│ ├─ Receives user credentials │\n│ ├─ Stores in memory (not disk!) │\n│ ├─ Reinitializes model factory │\n│ └─ Ready to analyze │\n└─────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────┐\n│ Analysis Ready │\n│ ├─ User can upload data │\n│ ├─ Run statistical tests │\n│ └─ View results │\n└─────────────────────────────────────┘\n```\n\n### UI Flow\n\n1. **First Visit** - User sees credential setup page\n2. **Enter Credentials** - Fill in at least one API provider\n3. **Configure** - Click \"Configure & Start\"\n4. **Success** - Redirected to main analysis page\n5. **Session** - Credentials stored in memory for session\n6. **Change Keys** - Can reconfigure anytime via \"⚙️ Change Keys\" button\n\n### UI Indicators\n\nWhen running in PROD mode, you'll see:\n- 🔐 **PROD MODE** - User credentials active\n- ⚙️ **Change Keys** button to reconfigure\n\n---\n\n## 🔐 Security Considerations\n\n### DEV Mode Security\n\n✅ **DO:**\n- Keep `.env` file local only (it's in `.gitignore`)\n- Use personal API keys with limited quota\n- Never commit `.env` to version control\n- Rotate keys if exposed\n\n❌ **DON'T:**\n- Share your `.env` file\n- Commit API keys to git\n- Use production API keys in dev\n\n### PROD Mode Security\n\n✅ **DO:**\n- Users provide their own API keys\n- Keys stored only in memory (runtime)\n- Keys never written to disk\n- Each user uses their own quota\n- Use HTTPS in production\n- Implement authentication (future)\n\n❌ **DON'T:**\n- Store user API keys in database\n- Log API keys\n- Share keys between users\n- Include keys in error messages\n\n### Credential Storage\n\n| Mode | Storage Location | Persistence | Security |\n|------|-----------------|-------------|----------|\n| **DEV** | `.env` file | Until manually changed | Git-ignored |\n| **PROD** | Memory only | Session only | Never saved |\n\n---\n\n## 📋 Makefile Commands\n\n### Quick Reference\n\n```bash\n# Development\nmake dev # Run in DEV mode (uses .env)\nmake api # Run only API (DEV)\nmake ui # Run only UI\n\n# Production\nmake prod # Run in PROD mode (user credentials)\nmake prod-api # Run only API (PROD)\nmake prod-ui # Run only UI (PROD)\n\n# Setup\nmake install # Install dependencies\nmake setup-env # Create .env from template\nmake db-init # Initialize database\nmake db-seed # Add sample data\n\n# Utilities\nmake clean # Clean temporary files\nmake status # Check system status\nmake help # Show all commands\n```\n\n### Detailed Commands\n\n#### `make dev`\n\nRuns in development mode:\n- Checks for `.env` file\n- Validates API keys are configured\n- Initializes database if needed\n- Starts FastAPI backend\n- ⚠️ You need to start UI separately: `make ui`\n\n#### `make prod`\n\nRuns in production mode:\n- Sets `ENVIRONMENT=production`\n- Starts API without loading `.env` keys\n- Starts UI which prompts for credentials\n- Users enter keys through web interface\n\n#### `make setup-env`\n\nCreates `.env` file from `.env.example`:\n```bash\nmake setup-env\n# Edit .env and add your keys\nnano .env\n```\n\n#### `make status`\n\nCheck current system status:\n```bash\nmake status\n\n# Output:\n# System Status:\n# Environment:\n# ✓ .env file exists\n# Database:\n# ✓ Database exists\n# API Keys Configured:\n# ✓ OpenAI\n# ✗ Anthropic\n# ✗ Google\n# ✗ Groq\n# ✓ Ollama (Local)\n```\n\n---\n\n## 🆓 Using Free Local Models (Ollama)\n\nBoth DEV and PROD modes support **Ollama** for completely free, private, local AI models!\n\n### Setup Ollama\n\n```bash\n# 1. Install Ollama\n# Visit: https://ollama.ai\n\n# 2. Pull a reasoning model\nollama pull deepseek-r1:8b\n\n# 3. Start Ollama server\nollama serve\n```\n\n### Configure for DEV Mode\n\nAdd to `.env`:\n```ini\nOLLAMA_ENABLED=true\nOLLAMA_BASE_URL=http://localhost:11434/v1\nOLLAMA_DEFAULT_MODEL=deepseek-r1:8b\n```\n\n### Configure for PROD Mode\n\nIn the credential setup UI:\n1. Go to \"Ollama (Local)\" tab\n2. Check \"Enable Ollama\"\n3. Set URL: `http://localhost:11434/v1`\n4. Set Model: `deepseek-r1:8b`\n5. Click \"Configure & Start\"\n\n### Why Ollama?\n\n- 🆓 **Completely FREE** - No API costs\n- 🔒 **Private** - Data never leaves your machine\n- ⚡ **Fast** - Local inference\n- 🧠 **Powerful** - DeepSeek-R1 excellent for reasoning\n- 📦 **Easy** - One command to install\n\n---\n\n## 🚦 Mode Comparison\n\n| Feature | Development Mode | Production Mode |\n|---------|------------------|-----------------|\n| **API Keys Source** | `.env` file | User input (UI) |\n| **Setup Complexity** | Easy (one-time) | Minimal (per user) |\n| **Security** | Local only | Session-based |\n| **Best For** | Developers | End users |\n| **Credential Sharing** | No sharing | Each user owns keys |\n| **Persistence** | File-based | Memory only |\n| **Startup** | `make dev` | `make prod` |\n| **Environment Var** | `ENVIRONMENT=development` | `ENVIRONMENT=production` |\n\n---\n\n## 🐛 Troubleshooting\n\n### Issue: \"No models configured\" in DEV mode\n\n**Solution:**\n```bash\n# Check if .env exists\ncat .env | grep API_KEY\n\n# Create if missing\nmake setup-env\n\n# Add your key\necho \"OPENAI_API_KEY=sk-...\" >> .env\n\n# Restart\nmake dev\n```\n\n### Issue: Stuck on credential page in PROD mode\n\n**Solution:**\n```bash\n# Check environment\ncurl http://localhost:8000/api/v1/models/environment\n\n# Should return: {\"environment\": \"production\", ...}\n\n# If wrong, fix and restart:\nexport ENVIRONMENT=production\nmake prod-api\n```\n\n### Issue: Keys not working after entering in UI\n\n**Possible causes:**\n1. Invalid API key format\n2. API key has no quota/credits\n3. Network issues reaching AI provider\n\n**Solution:**\n```bash\n# Check API logs\ntail -f data/logs/*.log\n\n# Test key manually\ncurl https://api.openai.com/v1/models \\\n -H \"Authorization: Bearer YOUR_KEY\"\n```\n\n### Issue: Can't switch from PROD to DEV mode\n\n**Solution:**\n```bash\n# Stop all processes\npkill -f \"statmate\"\n\n# Set environment\nexport ENVIRONMENT=development\n\n# Restart\nmake dev\n```\n\n---\n\n## 📚 Related Documentation\n\n- [Quick Start Guide](QUICK_START.md) - First-time setup\n- [Architecture Proposal](ARCHITECTURE_PROPOSAL.md) - System design\n- [API Reference](API_REFERENCE.md) - API endpoints\n- [Model Configuration](MODEL_CONFIGURATION.md) - AI model setup\n\n---\n\n## 🔄 Migration Between Modes\n\n### DEV → PROD\n\n```bash\n# 1. Stop dev server\n^C # Ctrl+C\n\n# 2. Remove API keys from .env (or create new .env)\ncat > .env << EOF\nENVIRONMENT=production\nDEBUG=false\nEOF\n\n# 3. Start in prod mode\nmake prod\n\n# 4. Users enter credentials via UI\n```\n\n### PROD → DEV\n\n```bash\n# 1. Stop prod server\n^C # Ctrl+C\n\n# 2. Add your API keys to .env\nmake setup-env\nnano .env # Add keys\n\n# 3. Start in dev mode\nmake dev\n```\n\n---\n\n## ✅ Best Practices\n\n### For Developers\n\n1. **Always use DEV mode** for local development\n2. **Never commit `.env`** to git (already in `.gitignore`)\n3. **Use `.env.example`** as template for team members\n4. **Rotate keys** if accidentally exposed\n5. **Use Ollama** for free local testing\n\n### For Deployment\n\n1. **Always use PROD mode** for hosted instances\n2. **Never include API keys** in deployment configs\n3. **Use HTTPS** in production\n4. **Implement rate limiting** to prevent abuse\n5. **Add authentication** for multi-user deployments\n6. **Use PostgreSQL** instead of SQLite\n7. **Monitor usage** and set quotas\n\n### For End Users\n\n1. **Use your own API keys** (don't share)\n2. **Start with Ollama** (free and private)\n3. **Monitor your usage** on provider dashboard\n4. **Set spending limits** on API accounts\n5. **Your keys = Your control** over costs\n\n---\n\n## 🎯 Quick Decision Guide\n\n**Choose DEV mode if:**\n- ✅ You're developing/testing locally\n- ✅ You're the only user\n- ✅ You want persistent configuration\n- ✅ You trust your local environment\n\n**Choose PROD mode if:**\n- ✅ Deploying for multiple users\n- ✅ Each user should use their own keys\n- ✅ Running on a shared server\n- ✅ You want session-based security\n\n---\n\n**Happy analyzing! 📊🚀**\n\n"}}}} |