Skip to content

SETUP.md

Latest commit

 

History

History
275 lines (210 loc) · 4.95 KB

SETUP.md

File metadata and controls

275 lines (210 loc) · 4.95 KB

📦 Setup Guide

Detailed installation instructions for the Intelligence Knowledge Graph System.

System Requirements

  • Operating System: macOS, Linux, or Windows 10+
  • Python: 3.11 or higher
  • Node.js: 18.x or higher
  • Docker: 20.x or higher
  • RAM: Minimum 8GB (16GB recommended)
  • Disk Space: 5GB free space

Step-by-Step Installation

1. Install Prerequisites

Python 3.11:

# macOS (using Homebrew)
brew install python@3.11

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install python3.11 python3.11-venv

# Windows
# Download from python.org

Node.js 18:

# macOS
brew install node@18

# Linux
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
# Download from nodejs.org

Docker:

# macOS
brew install docker

# Linux
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Windows
# Download Docker Desktop from docker.com

2. Clone Repository

git clone https://github.com/Fredbcx/intelligence-knowledge-graph.git
cd intelligence-knowledge-graph

3. Neo4j Database Setup

# Start Neo4j container
docker run -d \
  --name neo4j \
  -p 7474:7474 \
  -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password123 \
  neo4j:5.15.0-community

# Verify it's running
docker ps | grep neo4j

# Access Neo4j browser
# Open http://localhost:7474
# Login with neo4j/password123

4. Backend Setup

cd backend

# Create virtual environment
python3.11 -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate  # Windows

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Download spaCy language model
python -m spacy download en_core_web_lg

# Create environment file
cp .env.example .env

# Edit .env with your settings
nano .env  # or use your preferred editor

Edit .env file:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password123
API_HOST=0.0.0.0
API_PORT=8000

5. Frontend Setup

cd ../frontend

# Install dependencies
npm install

# Verify installation
npm list react

6. Load Sample Data (Optional)

cd ../backend

# Run data loading script
python load_sample_data.py

# This will:
# - Connect to Neo4j
# - Load sample entities and relationships
# - Verify graph structure

7. Start Services

Terminal 1 - Backend API:

cd backend
source venv/bin/activate
python analytics_app.py

# Should see:
# INFO: Started server process
# INFO: Uvicorn running on http://0.0.0.0:8000

Terminal 2 - Frontend Dashboard:

cd frontend
npm run dev

# Should see:
# VITE ready in Xms
# Local: http://localhost:3000

8. Verify Installation

Check all services:

# Neo4j
curl http://localhost:7474
# Should return Neo4j browser HTML

# Backend API
curl http://localhost:8000/api/v1/health
# Should return: {"status": "healthy", "graph_loaded": true}

# Frontend
# Open browser: http://localhost:3000
# Should see dashboard with 4 tabs

Troubleshooting

Neo4j won't start

# Check if port 7474 is already in use
lsof -i :7474

# Stop existing Neo4j container
docker stop neo4j
docker rm neo4j

# Start fresh
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password123 \
  neo4j:5.15.0-community

Backend API errors

# Verify Neo4j connection
python -c "from neo4j import GraphDatabase; driver = GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'password123')); driver.verify_connectivity(); print('Connected!')"

# Check if spaCy model is installed
python -m spacy validate

# Reinstall if needed
python -m spacy download en_core_web_lg

Frontend won't start

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules
npm install

# Check Node version
node --version  # Should be 18.x or higher

Port conflicts

# Backend running on different port
export API_PORT=8001
python analytics_app.py

# Update frontend API URL
# Edit frontend/src/services/api.ts
# Change baseURL to 'http://localhost:8001'

Next Steps

After successful installation:

  1. Explore the dashboard at http://localhost:3000
  2. Check API docs at http://localhost:8000/docs
  3. View graph in Neo4j at http://localhost:7474
  4. Add your own documents in backend/data/documents/
  5. Process new data using the document processor

Development Workflow

# Make backend changes
cd backend
# Edit code
python analytics_app.py  # Server auto-reloads

# Make frontend changes
cd frontend
# Edit React components
# Vite hot-reloads automatically

# Run tests
cd backend
pytest tests/ -v

cd frontend
npm test

Production Deployment

For production deployment, see DEPLOYMENT.md (coming soon).

Quick Docker Compose setup:

docker-compose up -d

This will start all services in containers.