Skip to main content

Development Setup

Set up your local Korad.AI development environment.

Prerequisites​

  • Python 3.10+
  • PostgreSQL 14+ (or use Docker)
  • Node.js 18+ (for user portal)
  • Stripe account (for payment testing)

Quick Start​

# Clone the repository
git clone https://github.com/WeathermanTony/korad.ai.git
cd korad.ai

# Install dependencies
pip install -r requirements/base.txt

# Start PostgreSQL (Docker)
docker compose up -d db redis

# Set environment variables
cp .env.example .env
# Edit .env with your keys

# Run migrations
python scripts/migrate_db.py

# Start the server
./start_dev.sh

Access at http://localhost:8080

Environment Variables​

Required Variables​

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/korad_dev

# API Keys
LITELLM_MASTER_KEY=sk-dev-master-key-change-me
DEEPSEEK_API_KEY=sk-your-deepseek-key
XAI_API_KEY=xai-your-grok-key

# Stripe (for payments)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Clerk (for auth)
CLERK_SECRET_KEY=sk_test_...
CLERK_WEBHOOK_SECRET=...

Optional Variables​

# Redis (caching)
REDIS_HOST=localhost
REDIS_PORT=6379

# Development
ENVIRONMENT=development
PORT=8080
DEBUG=true

# Initial credit for new users
INITIAL_CREDIT=0.0

Running Locally​

Development Server​

./start_dev.sh

Staging Server​

./start_staging.sh

Production (Local)​

./start_prod_local.sh

Database Setup​

docker compose up -d db redis

Manual PostgreSQL​

# Create database
createdb korad_dev

# Run migrations
python scripts/migrate_db.py

# Seed data (optional)
python scripts/seed_db.py

Testing​

Run All Tests​

pytest tests/

Run Specific Tests​

# API tests
pytest tests/test_api.py

# Database tests
pytest tests/test_database.py

# Stripe webhook tests
python scripts/test_stripe_webhook.py

Test Coverage​

pytest --cov=. --cov-report=html

Stripe Testing​

Setup Stripe CLI for local testing
# Install Stripe CLI
./scripts/setup_stripe_cli.sh

# Login
stripe login

# Forward webhooks (in separate terminal)
./scripts/stripe_forward.sh

# Trigger test events
./scripts/stripe_test.sh

Project Structure​

korad.ai/
├── custom/
│   ├── callbacks.py       # Context optimization
│   ├── database.py        # Database operations
│   └── clerk_auth.py      # Clerk integration
├── stripe_webhook.py      # Stripe payment handling
├── clerk_webhook.py       # Clerk user provisioning
├── admin_endpoints.py     # Admin API
├── start.py               # Application entry point
├── scripts/
│   ├── start_dev.sh       # Development server
│   ├── stripe_test.sh     # Stripe test suite
│   └── setup_stripe_cli.sh
├── user-portal/           # Next.js frontend
├── docusaurus-docs/       # Documentation
└── docs/                  # Additional docs

Common Tasks​

Add a New API Provider​

  1. Add provider key to .env
  2. Update litellm_config.yaml
  3. Test with:
curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer sk-dev-master-key-change-me"

Add a New Credit Package​

Edit stripe_webhook.py:

CREDIT_PACKAGES = {
    "starter": {"price_cents": 1000, "credits": 100000, "name": "Starter ($10)"},
    # Add new package
    "mega": {"price_cents": 100000, "credits": 10000000, "name": "Mega ($1k)"},
}

Clear Database​

docker compose down -v
docker compose up -d db
python scripts/migrate_db.py

Troubleshooting​

Port Already in Use​

# Find process using port 8080
lsof -i :8080

# Kill it
kill -9 <PID>

Database Connection Failed​

# Check PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs korad-db-1

# Restart
docker compose restart db

Stripe Webhook Not Receiving​

# Verify Stripe CLI is forwarding
./scripts/stripe_forward.sh

# Check webhook secret matches
echo $STRIPE_WEBHOOK_SECRET

Next Steps​