DEPLOYMENT.md

CVE Fact Checker - Deployment Guide

Quick Start

Local Development

python -m pip install -r requirements.txt
python -m cve_factchecker

Production (Docker)

docker build -t cve-fact-checker .
docker run -p 7860:7860 cve-fact-checker

Health Check

python health_check.py

Environment Variables

Variable	Description	Default
PORT	Server port	7860
OPENROUTER_API_KEY	LLM API key	None
FIREBASE_API_KEY	Firebase API key	(embedded)
AUTO_INGEST	Auto-ingest on startup	true
LANGUAGE_FILTER	Language to filter articles	English
USE_DUMMY_EMBEDDINGS	Use lightweight embeddings	false
VECTOR_PERSIST_DIR	Vector DB directory	/tmp/vector_db
SENTENCE_TRANSFORMERS_HOME	Model cache	/tmp/sentence_transformers

API Endpoints

Health Check

curl http://localhost:7860/health

Fact Check

# GET request
curl "http://localhost:7860/fact-check?claim=Your claim here"

# POST request (JSON)
curl -X POST http://localhost:7860/fact-check \
  -H "Content-Type: application/json" \
  -d '{"claim": "Your claim here"}'

# POST request (form data)
curl -X POST http://localhost:7860/fact-check \
  -F "claim=Your claim here"

Troubleshooting

Common Issues

Permission Denied Errors

• Symptom: [Errno 13] Permission denied: './vector_db'
• Solution: The app automatically falls back to /tmp/vector_db or in-memory storage

Firebase Rate Limiting

• Symptom: Firebase API failed: 429
• Solution: The app implements exponential backoff and retry logic

Model Loading Issues

• Symptom: No sentence-transformers model found
• Solution: Set USE_DUMMY_EMBEDDINGS=true for faster startup

Memory Issues

• Symptom: App crashes or becomes unresponsive
• Solution: Reduce batch sizes or enable dummy embeddings

Debug Mode

Run with debug logging:

export FLASK_ENV=development
python -m cve_factchecker

Manual Health Check

The health_check.py script provides comprehensive diagnostics:

python health_check.py

This checks:

• Environment variables
• Directory permissions
• Package imports
• Firebase connectivity
• App functionality

Production Deployment

For production use:

python run_production.py

This script:

• Runs health checks
• Sets up signal handlers
• Starts gunicorn with optimal settings
• Provides better error reporting

Docker Configuration

The Dockerfile is optimized for containerized deployment:

• Uses Python 3.11 slim base
• Creates writable cache directories
• Single worker to avoid race conditions
• Proper signal handling
• Health check integration

Architecture

CVE Fact Checker
├── Flask Web API
├── Vector Database (ChromaDB)
├── Embeddings (sentence-transformers)
├── Firebase Article Loader
└── LLM Integration (OpenRouter)

Performance Tuning

For Low-Memory Environments

export USE_DUMMY_EMBEDDINGS=true
export AUTO_INGEST=false

For High-Throughput

export AUTO_INGEST=true
# Ensure adequate Firebase API limits

Support

If you encounter issues:

1. Run python health_check.py for diagnostics
2. Check application logs for specific errors
3. Verify environment variables are set correctly
4. Ensure proper file system permissions