Local Development Setup

This guide walks you through setting up Clipron AI on your local machine for development, testing, or evaluation purposes.

Local development setup is perfect for testing, customization, and contributing to the project. For production deployment, see our Production Deployment Guide.

Prerequisites

Before starting, ensure you have the following installed:

Git

Version control

Git 2.25+ recommended
GitHub account for cloning
SSH keys configured (optional)

Python 3.9+

Backend runtime

Python 3.9, 3.10, or 3.11
pip package manager
venv module for virtual environments

Node.js 18+

Frontend build tools

Node.js 18 LTS or newer
npm package manager (included)
Build tools for native modules

Code Editor

Development environment

VS Code (recommended)
PyCharm or similar IDE
Extensions for Python and React

Quick Start

1. Clone the Repository

# Clone the repository
git clone https://github.com/clipron/clipron-ai.git
cd clipron-ai

# Make scripts executable
chmod +x *.sh

2. Automated Setup

The fastest way to get started is using our automated setup script:

# Run the automated installation script
./install_ai_dependencies.sh

This script will:

Create Python virtual environment
Install all Python dependencies
Install Node.js dependencies
Set up basic configuration files
Initialize the database

3. Manual Setup (Alternative)

If you prefer manual setup or the automated script fails:

Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Install additional development tools
npm install -g @types/node typescript

Database Initialization

# Return to backend directory
cd backend
source venv/bin/activate

# Initialize database
python init_db.py

Configuration

Environment Variables

Create configuration files from templates:

Backend Configuration
Frontend Configuration

# Copy backend environment template
cd backend
cp .env.example .env

Edit backend/.env with your settings:

# Database (SQLite for development)
DATABASE_URL=sqlite:///./clipron.db

# Security
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Development settings
ENVIRONMENT=development
DEBUG=true
FRONTEND_URL=http://localhost:3000

# Copy frontend environment template
cd frontend
cp .env.development.example .env.development

Edit frontend/.env.development:

# API Configuration
REACT_APP_API_URL=http://localhost:8000
REACT_APP_ENVIRONMENT=development

# Feature flags
REACT_APP_ENABLE_ANALYTICS=false
REACT_APP_ENABLE_SENTRY=false

API Keys (Optional for Basic Testing)

For full functionality, you’ll need API keys. Add these to backend/.env:

AI Model APIs (Optional)

# At least one AI API key for analysis functionality
GOOGLE_GEMINI_API_KEY=your_google_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key

Without AI API keys, you can still test the UI and basic functionality, but code analysis won’t work.

OAuth (Optional)

# Google OAuth (optional)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# GitHub OAuth (optional)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

Without OAuth, you can still create accounts using email/password authentication.

Stripe (Optional)

# Stripe for payment processing (optional)
STRIPE_SECRET_KEY=sk_test_your_test_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

Without Stripe, the credit system will work in “free mode” with unlimited credits.

Running the Application

Development Servers

You’ll need to run both backend and frontend servers simultaneously:

Backend Server
Frontend Server

# Terminal 1: Backend
cd backend
source venv/bin/activate

# Run development server
python main.py

The backend will start on http://localhost:8000Available endpoints:

API: http://localhost:8000/api
Docs: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

# Terminal 2: Frontend
cd frontend

# Run development server
npm start

The frontend will start on http://localhost:3000Features:

Hot reload for code changes
React DevTools support
Source maps for debugging

Using Development Scripts

For convenience, you can use the provided scripts:

# Start both servers (requires tmux or screen)
./start-dev.sh

# Stop all development servers
./stop-dev.sh

# Reset database and restart
./reset-dev.sh

Development Workflow

Making Changes

Backend Changes

Edit Python files in backend/
Server automatically reloads on file changes
Check logs in terminal for errors
Test API endpoints at http://localhost:8000/docs

Frontend Changes

Edit React files in frontend/src/
Browser automatically refreshes on save
Check browser console for errors
Use React DevTools for debugging

Database Changes

Modify models in backend/models/
Create migration: alembic revision --autogenerate -m "description"
Apply migration: alembic upgrade head
Or reset database: python init_db.py

Testing

Backend Testing

cd backend
source venv/bin/activate

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_auth.py

Frontend Testing

cd frontend

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Integration Testing

# Test API endpoints
./test-api.sh

# Test AI functionality (requires API keys)
python backend/quick_ai_test.py

# Health check
./health-check.sh

Development Tools

Recommended VS Code Extensions

Python Extensions

Python (Microsoft)
Pylance
Python Docstring Generator
autoDocstring

React Extensions

ES7+ React/Redux/React-Native snippets
Bracket Pair Colorizer
Auto Rename Tag
Prettier - Code formatter

General Extensions

GitLens
Thunder Client (API testing)
REST Client
Docker (if using containers)

Database Extensions

SQLite Viewer
PostgreSQL (if using PostgreSQL)
Database Client JDBC

Debugging

Backend Debugging
Frontend Debugging

VS Code Python Debugging:

Set breakpoints in Python code
Press F5 or use “Run and Debug”
Select “Python: FastAPI” configuration
Debug requests step-by-step

Manual debugging:

import pdb; pdb.set_trace()  # Add to code

Browser DevTools:

Open browser DevTools (F12)
Use Console tab for JavaScript errors
Use Network tab for API calls
Use React DevTools for component state

VS Code debugging:

debugger;  // Add to JavaScript code

Common Development Issues

Port Conflicts

Backend Port 8000 in Use

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or use different port
uvicorn main:app --port 8001

Frontend Port 3000 in Use

# React will automatically suggest port 3001
# Or set specific port
PORT=3001 npm start

Database Issues

Database Locked

# Stop all processes using database
pkill -f "python main.py"

# Remove database file
rm backend/clipron.db

# Reinitialize
python backend/init_db.py

Migration Errors

# Reset migrations
rm -rf backend/alembic/versions/*

# Create new initial migration
cd backend
alembic revision --autogenerate -m "initial"
alembic upgrade head

Dependency Issues

Python Dependencies

# Update pip
pip install --upgrade pip

# Reinstall requirements
pip install -r requirements.txt --force-reinstall

# Clear pip cache
pip cache purge

Node.js Dependencies

# Clear npm cache
npm cache clean --force

# Remove node_modules
rm -rf node_modules package-lock.json

# Reinstall
npm install

Next Steps

Production Deployment

Deploy Clipron AI to a production server

API Documentation

Explore the complete API reference

Contributing

Learn how to contribute to the project

Troubleshooting

Solve common development issues

Pro Tip: Use tmux or screen to run both backend and frontend servers in a single terminal session. This makes development much more convenient.

Introduction

Getting Started

Installation & Deployment

Architecture

User Guides

Troubleshooting

​Local Development Setup

​Prerequisites

Git

Python 3.9+

Node.js 18+

Code Editor

​Quick Start

​1. Clone the Repository

​2. Automated Setup

​3. Manual Setup (Alternative)

​Configuration

​Environment Variables

​API Keys (Optional for Basic Testing)

​Running the Application

​Development Servers

​Using Development Scripts

​Development Workflow

​Making Changes

​Testing

​Development Tools

​Recommended VS Code Extensions

Python Extensions

React Extensions

General Extensions

Database Extensions

​Debugging

​Common Development Issues

​Port Conflicts

​Database Issues

​Dependency Issues

​Next Steps

Production Deployment

API Documentation

Contributing

Troubleshooting

Local Development Setup

Prerequisites

Quick Start

1. Clone the Repository

2. Automated Setup

3. Manual Setup (Alternative)

Configuration

Environment Variables

API Keys (Optional for Basic Testing)

Running the Application

Development Servers

Using Development Scripts

Development Workflow

Making Changes

Testing

Development Tools

Recommended VS Code Extensions

Debugging

Common Development Issues

Port Conflicts

Database Issues

Dependency Issues

Next Steps