docs/technical/NEO4J_SETUP_GUIDE.md

🕸️ NEO4J SETUP GUIDE

Date: 2025-11-24
Status: ⚠️ Neo4j Not Yet Installed

---

🎯 OVERVIEW

Neo4j er ikke installeret endnu. Vi har implementeret Neo4jGraphAdapter, men Neo4j serveren skal startes først.

---

📦 INSTALLATION OPTIONS

Option 1: Docker (Recommended) ✅

Quick Start:

docker run \
  --name neo4j-widgetdc \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc"]' \
  -d \
  neo4j:5.15

With Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  neo4j:
    image: neo4j:5.15
    ports:
      - "7474:7474"  # HTTP
      - "7687:7687"  # Bolt
    environment:
      NEO4J_AUTH: neo4j/password
      NEO4J_PLUGINS: '["apoc"]'
    volumes:
      - neo4j_data:/data
      - neo4j_logs:/logs
    healthcheck:
      test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "password", "RETURN 1"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  neo4j_data:
  neo4j_logs:

Start:

docker-compose up -d neo4j

---

Option 2: Local Installation

Ubuntu/Debian:

wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -
echo 'deb https://debian.neo4j.com stable latest' | sudo tee -a /etc/apt/sources.list.d/neo4j.list
sudo apt-get update
sudo apt-get install neo4j
sudo systemctl start neo4j

macOS:

brew install neo4j
brew services start neo4j

Windows: Download installer from: https://neo4j.com/download/

---

⚙️ CONFIGURATION

Environment Variables

Create .env file in apps/backend/:

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j

Default Values (if not set):

• URI: bolt://localhost:7687
• Username: neo4j
• Password: password
• Database: neo4j

---

🔍 VERIFICATION

Check if Neo4j is Running

1. Check Docker:

docker ps | grep neo4j

2. Check HTTP Port:

curl http://localhost:7474

3. Check Bolt Port:

nc -zv localhost 7687

4. Test Connection:

# Using cypher-shell (if installed)
cypher-shell -u neo4j -p password "RETURN 1"

---

🚀 QUICK START (Docker)

# 1. Start Neo4j
docker run -d \
  --name neo4j-widgetdc \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.15

# 2. Wait for startup (30-60 seconds)
sleep 30

# 3. Verify connection
curl http://localhost:7474

# 4. Set environment variables
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password

# 5. Start backend
cd apps/backend
npm run dev

---

🔧 APOC PLUGIN (Optional but Recommended)

APOC (Awesome Procedures on Cypher) provides additional procedures:

# Docker with APOC
docker run -d \
  --name neo4j-widgetdc \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5.15

APOC Features:

• Additional graph algorithms
• Data import/export
• Text processing
• Time functions

---

📊 CURRENT STATUS

✅ What We Have

• ✅ Neo4j driver installed (neo4j-driver@6.0.1)
• ✅ Neo4jGraphAdapter implemented
• ✅ Integration code ready
• ✅ Graceful degradation (continues without Neo4j)

❌ What's Missing

• ❌ Neo4j server not running
• ❌ No Docker container
• ❌ No local installation

---

🎯 RECOMMENDED ACTION

Use Docker (Easiest):

# Create docker-compose.yml in project root
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  neo4j:
    image: neo4j:5.15
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/password
      NEO4J_PLUGINS: '["apoc"]'
    volumes:
      - neo4j_data:/data
    healthcheck:
      test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "password", "RETURN 1"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  neo4j_data:
EOF

# Start Neo4j
docker-compose up -d neo4j

# Verify
sleep 30
curl http://localhost:7474

---

🔗 USEFUL LINKS

• Neo4j Docker Hub: https://hub.docker.com/_/neo4j
• Neo4j Documentation: https://neo4j.com/docs/
• Cypher Query Language: https://neo4j.com/docs/cypher-manual/
• APOC Procedures: https://neo4j.com/labs/apoc/

---

⚠️ NOTES

1. Default Password: First-time setup requires password change via browser UI
2. Ports: 7474 (HTTP), 7687 (Bolt)
3. Memory: Neo4j needs ~2GB RAM minimum
4. Data Persistence: Use Docker volumes for data persistence
5. Graceful Degradation: System works without Neo4j (uses implicit patterns)

---

Status: ⚠️ Neo4j Not Installed - Setup Required
Next Action: Start Neo4j using Docker or local installation