Skip to main content

​
Overview

CheckThat AI can be set up for local development using automated scripts or manual configuration. The platform runs two services:
  • Frontend: React + TypeScript + Vite (Port 5173)
  • Backend: FastAPI + Python (Port 8000)

​
Prerequisites

Before starting, ensure you have the following installed:

Node.js

Version 18 or higher required

Python

Version 3.8 or higher required

Git

For cloning the repository

API Keys

OpenAI, Anthropic, Gemini, or xAI
The project includes automation scripts that handle the entire setup process automatically.
1

Clone the Repository

git clone https://github.com/nikhil-kadapala/clef2025-checkthat-lab-task2.git
cd clef2025-checkthat-lab-task2
2

Configure Environment Variables

Set up your API keys before running the setup script:
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GEMINI_API_KEY="your-gemini-key"
export GROK_API_KEY="your-grok-key"
You only need the API keys for the model providers you plan to use. At least one provider is required.
3

Run Automated Setup

Make the setup script executable and run it:
chmod +x setup-project.sh
./setup-project.sh
The script will:
  • ✅ Detect your operating system (Linux/macOS/Windows)
  • ✅ Terminate conflicting processes on port 5173
  • ✅ Install Node.js dependencies for the frontend
  • ✅ Fix npm security vulnerabilities automatically
  • ✅ Create Python virtual environment
  • ✅ Install Python dependencies using uv (faster) or pip
  • ✅ Handle cross-platform compatibility
You only need to run this script once for initial setup.
4

Start the Application

After setup completes, start both services:
chmod +x run-project.sh
./run-project.sh
The application will start:
  • Frontend: http://localhost:5173
  • Backend: http://localhost:8000
The script displays process IDs for monitoring. Press Ctrl+C to gracefully shut down both services.
5

Access the Application

Open your browser and navigate to:
http://localhost:5173
The API documentation is available at:
http://localhost:8000/docs

​
What the Scripts Do

​
setup-project.sh

Automatically detects and terminates conflicting processes on port 5173 using platform-specific commands:
  • Linux/macOS: Uses lsof or ss to identify and kill processes
  • Windows: Uses netstat and taskkill commands
  • Clears npm cache to avoid conflicts
  • Installs all Node.js dependencies in src/app
  • Runs npm audit fix to address security vulnerabilities
  • Replaces deprecated @esbuild-kit packages with tsx
  • Installs uv for faster Python package management
  • Creates Python virtual environment in .venv
  • Activates virtual environment (platform-specific paths)
  • Installs Python dependencies from requirements.txt
  • Falls back to standard pip if uv fails

​
run-project.sh

  • Checks for and terminates existing processes on port 5173
  • Starts frontend with npm run dev in background
  • Starts backend with fastapi dev main.py --host 0.0.0.0 --port 8000
  • Stores process IDs for cleanup on exit
  • Traps Ctrl+C signal for clean shutdown
  • Terminates both frontend and backend processes
  • Ensures no orphaned processes remain

​
Option 2: Manual Setup

If you prefer manual setup or encounter issues with the automated scripts:
1

Clone Repository

git clone https://github.com/nikhil-kadapala/clef2025-checkthat-lab-task2.git
cd clef2025-checkthat-lab-task2
2

Set Up Backend

Create and activate a Python virtual environment:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
3

Set Up Frontend

Install Node.js dependencies:
cd src/app
npm install
cd ../..
4

Configure Environment

Export your API keys (see Option 1, Step 2 for commands)
5

Start Services

Open two terminal windows:
cd src/api
source ../../.venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows
fastapi dev main.py --host 0.0.0.0 --port 8000

​
Port Configuration

The application uses the following ports by default:
ServicePortURL
Frontend5173http://localhost:5173
Backend API8000http://localhost:8000
API Docs8000http://localhost:8000/docs
If ports 5173 or 8000 are already in use, you’ll need to either:
  • Stop the conflicting service
  • Modify the port configuration in vite.config.ts (frontend) or main.py (backend)

​
Troubleshooting

​
Permission Denied on Scripts

If you get a permission error when running the scripts: 
chmod +x setup-project.sh run-project.sh

​
Windows Script Execution

On Windows, use Git Bash or WSL to run the shell scripts: 
bash setup-project.sh
bash run-project.sh

​
Port Already in Use

The scripts automatically handle port conflicts, but if you still encounter issues: 
lsof -ti:5173 | xargs kill -9

​
API Keys Not Working

Verify your API keys are set correctly:
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
If empty, re-export them before running the scripts.
Ensure there are no extra spaces or quotes in your API keys:
  • ✅ Correct: export OPENAI_API_KEY=sk-proj-...
  • ❌ Wrong: export OPENAI_API_KEY="sk-proj-..." (extra quotes)
Test your API key directly with a curl command or the provider’s dashboard to ensure it’s valid and has sufficient quota.

​
Frontend Build Errors

cd src/app
rm -rf node_modules package-lock.json
npm install
Ensure you’re using Node.js v18 or higher:
node --version
If outdated, download the latest version from nodejs.org
npm install -g npm@latest

​
Backend Import Errors

Ensure the virtual environment is activated:
# You should see (.venv) in your prompt
which python  # Should point to .venv/bin/python

source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

python --version  # Should be 3.8 or higher

​
NLTK Data Missing

If you encounter NLTK data errors when using METEOR scoring: 
import nltk
nltk.download('wordnet')
nltk.download('punkt')
nltk.download('omw-1.4')

​
Development Workflow

Once set up, your typical development workflow:
  1. Start Development: Run ./run-project.sh
  2. Make Changes: Edit files in src/app (frontend) or src/api (backend)
  3. Hot Reload: Both services automatically reload on file changes
  4. Stop Services: Press Ctrl+C in the terminal
The frontend uses Vite’s hot module replacement (HMR), so changes appear instantly without full page reloads.

​
Next Steps

Environment Variables

Configure API keys and settings

Production Deployment

Deploy to production environments

API Reference

Explore the API endpoints

Model Configuration

Configure AI model providers

Build docs developers (and LLMs) love

Get started for freeTalk to us