Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
285 lines (207 loc) · 5.87 KB

SETUP_GUIDE.md

File metadata and controls

285 lines (207 loc) · 5.87 KB

iOps Complete Setup Guide

This guide covers everything you need to get the iOps application running locally.

Quick Start

# Terminal 1 - Backend
cd backend
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # Linux/Mac
pip install -r requirements.txt
cp .env.example .env           # Then edit .env with your values
python migrate.py upgrade
python create_test_user.py     # Creates a test user
python run.py

# Terminal 2 - Frontend
cd frontend
npm install
cp .env.example .env.local
npm run dev

URLs:

Prerequisites

Required Software

Software Version Purpose
Python 3.11+ Backend runtime
Node.js 18+ Frontend runtime
Git Latest Version control

Optional (Production)

  • PostgreSQL 12+ (SQLite works for development)
  • Redis (for background jobs)

Step 1: Backend Setup

1.1 Create Virtual Environment

cd backend
python -m venv venv

# Activate (choose your OS)
venv\Scripts\activate          # Windows CMD
.\venv\Scripts\Activate.ps1    # Windows PowerShell
source venv/bin/activate       # Linux/Mac

1.2 Install Dependencies

pip install -r requirements.txt

1.3 Configure Environment Variables

cp .env.example .env

Edit .env and configure these required variables:

Variable Description How to Get
SECRET_KEY JWT signing key python -c "import secrets; print(secrets.token_urlsafe(32))"
ENCRYPTION_KEY Data encryption python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
GROQ_API_KEY AI features console.groq.com

Optional variables for full functionality:

  • PAYSTACK_SECRET_KEY - Payment processing
  • RESEND_API_KEY - Email service
  • GOOGLE_CLIENT_ID/SECRET - Google Sheets integration

1.4 Initialize Database

python migrate.py upgrade

1.5 Create Test User

python create_test_user.py

This creates a user you can use to test the application.

Step 2: Frontend Setup

2.1 Install Dependencies

cd frontend
npm install

2.2 Configure Environment

cp .env.example .env.local

Default configuration works for local development:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

Step 3: Start the Application

3.1 Start Backend Server

cd backend
python run.py

Backend runs at: http://localhost:8000

3.2 Start Frontend Server (new terminal)

cd frontend
npm run dev

Frontend runs at: http://localhost:3000

Step 4: Verify Installation

  1. Open http://localhost:3000
  2. Register a new account or use the test user
  3. Upload a CSV file to test data processing
  4. Create an analysis to test AI features

Feature Testing Checklist

Core Features

  • User registration and login
  • Dashboard loads correctly
  • Upload CSV/Excel dataset
  • Create and execute analysis
  • AI Copilot chat functionality
  • Generate and share reports
  • Browse template marketplace

Admin Features (requires admin user)

  • Admin dashboard metrics
  • User management
  • Revenue analytics

API Endpoints Reference

Authentication

Endpoint Method Description
/api/auth/register POST User registration
/api/auth/login POST User login
/api/auth/me GET Get current user

Data & Analysis

Endpoint Method Description
/api/datasets GET/POST List/upload datasets
/api/analyses GET/POST List/create analyses
/api/analyses/{id}/execute POST Run analysis

Full API documentation available at: http://localhost:8000/docs

Troubleshooting

Backend Issues

"Module not found" errors

pip install -r requirements.txt

Database errors

python migrate.py upgrade

Port 8000 in use

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Linux/Mac
lsof -i :8000
kill -9 <PID>

Frontend Issues

API connection errors

  • Verify backend is running on port 8000
  • Check NEXT_PUBLIC_API_URL in .env.local

Build errors

rm -rf node_modules .next
npm install
npm run dev

External Services Setup

Groq AI (Required for AI features)

  1. Create account at console.groq.com
  2. Generate API key
  3. Add to GROQ_API_KEY in .env

Paystack (Payments)

  1. Create account at paystack.com
  2. Get API keys from dashboard
  3. Add to PAYSTACK_SECRET_KEY and PAYSTACK_PUBLIC_KEY

Google OAuth (Data Connections)

  1. Go to Google Cloud Console
  2. Create OAuth 2.0 credentials
  3. Set redirect URI: http://localhost:8000/api/connections/google-sheets/callback
  4. Add to GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

Resend (Email)

  1. Create account at resend.com
  2. Get API key
  3. Add to RESEND_API_KEY

Sentry (Error Monitoring)

  1. Create account at sentry.io
  2. Create a FastAPI project
  3. Add DSN to SENTRY_DSN

Production Deployment

For production deployment instructions, see docs/DEPLOYMENT.md.

Key considerations:

  • Use PostgreSQL instead of SQLite
  • Set DEBUG=false
  • Configure proper CORS origins
  • Use HTTPS
  • Set up monitoring (Sentry)

Getting Help