Skip to content

SETUP.md

Latest commit

 

History

History
325 lines (253 loc) · 7.49 KB

SETUP.md

File metadata and controls

325 lines (253 loc) · 7.49 KB
Raw

DocuChat Agent - Setup Guide

This guide provides multiple ways to set up DocuChat Agent on your system.

🚀 Quick Setup (Recommended)

Linux & macOS

# Make setup script executable
chmod +x setup_docuchat.sh

# Run interactive setup
./setup_docuchat.sh

# Or run automated setup
./setup_docuchat.sh --auto

Windows

# Run the Windows setup script
setup_docuchat.bat

# Or run automated setup
setup_docuchat.bat /auto

📋 What Gets Installed

The setup script automatically installs and configures:

  1. System Tools

    • Docker (if not present)
    • Tesseract OCR
    • Git and curl utilities

  2. Services

    • Neo4j Community Edition (Docker container)
    • Ollama LLM server with gemma2:2b model

  3. Python Environment

    • Virtual environment (venv/)
    • All Python dependencies
    • spaCy language model
    • Playwright browsers
    • DocuChat package installation

  4. Configuration

    • Data directories structure
    • ChromaDB initialization
    • Hardware profile generation
    • Service connectivity testing

⚙️ Setup Options

Interactive Mode (Default)

./setup_docuchat.sh
  • Asks for confirmation before major installations
  • Shows progress and detailed output
  • Recommended for first-time setup

Automated Mode

./setup_docuchat.sh --auto
  • No prompts, installs everything automatically
  • Ideal for CI/CD or scripted deployments
  • Uses safe defaults for all configurations

Resume from Specific Phase

./setup_docuchat.sh --resume-from=3
  • Resume from phase 3 (System Tools Installation)
  • Useful if setup was interrupted
  • Phases: 1=System Check, 2=Neo4j, 3=Tools, 4=Python, 5=Config, 6=Verification

Skip External Services

./setup_docuchat.sh --skip-docker --skip-ollama
  • Skip Docker/Neo4j setup (use existing installation)
  • Skip Ollama installation (use existing or cloud LLMs)
  • Useful for custom configurations

📋 Setup Phases

The setup process consists of 6 phases:

Phase 1: System Requirements Check

  • Detects operating system and package manager
  • Checks Python 3.10+ availability
  • Verifies Docker installation
  • Tests internet connectivity
  • Ensures sufficient disk space and memory

Phase 2: Neo4j Database Setup

  • Pulls Neo4j 5.15 Community Edition image
  • Creates persistent data volumes
  • Configures authentication (neo4j/docuchat123)
  • Sets up APOC plugin
  • Optimizes memory settings for performance

Phase 3: System Tools Installation

  • Installs Tesseract OCR for document image processing
  • Downloads and installs Ollama LLM server
  • Downloads gemma2:2b model (lightweight, fast)
  • Configures system services

Phase 4: Python Environment Setup

  • Creates isolated virtual environment
  • Installs all Python dependencies from requirements.txt
  • Downloads spaCy English language model
  • Installs Playwright browsers for web scraping
  • Installs DocuChat package in development mode

Phase 5: Service Configuration

  • Creates data directory structure
  • Initializes ChromaDB vector database
  • Tests Neo4j connectivity
  • Generates hardware optimization profile
  • Creates default configuration files

Phase 6: Verification and Testing

  • Tests DocuChat CLI functionality
  • Verifies all service connections
  • Creates sample test documents
  • Runs basic ingestion test
  • Generates setup completion report

🔧 Prerequisites

Minimum Requirements

  • OS: Linux, macOS, or Windows with WSL2
  • RAM: 4GB minimum, 8GB+ recommended
  • Storage: 10GB free space
  • Python: 3.10 or later
  • Internet: Required for downloads

Recommended Hardware

  • CPU: 4+ cores for optimal performance
  • RAM: 16GB for large document processing
  • Storage: SSD for better I/O performance
  • GPU: Not required (CPU-optimized)

🐛 Troubleshooting

Common Issues

1. Docker Permission Errors

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

2. Neo4j Container Won't Start

# Check container logs
docker logs docuchat-neo4j

# Restart container
docker restart docuchat-neo4j

3. Python Module Not Found

# Ensure virtual environment is activated
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate.bat  # Windows

# Reinstall packages
pip install -r requirements.txt

4. Ollama Service Not Responding

# Check Ollama status
curl http://localhost:11434/api/version

# Restart Ollama (Linux)
sudo systemctl restart ollama

5. Port Conflicts

# Check what's using the ports
netstat -tulpn | grep -E "(7474|7687|11434)"

# Stop conflicting services or change ports

Setup Logs

The setup script creates detailed logs:

  • Setup log: setup_docuchat.log
  • Docker logs: docker logs docuchat-neo4j
  • Service status: python -m docuchat status --check-all

🔄 Uninstallation

To completely remove DocuChat Agent:

# Stop and remove containers
docker stop docuchat-neo4j
docker rm docuchat-neo4j

# Remove Docker images (optional)
docker rmi neo4j:5.15-community

# Remove Python environment
rm -rf venv/

# Remove data directories (⚠️ this deletes all your data)
rm -rf data/ chroma/

# Uninstall system packages (optional)
# This varies by system - remove manually if desired

🌐 Network Configuration

Default ports used by DocuChat Agent:

  • 7474: Neo4j HTTP interface
  • 7687: Neo4j Bolt protocol
  • 11434: Ollama API server

Firewall Configuration

If running on a server, ensure these ports are accessible:

# Ubuntu/Debian
sudo ufw allow 7474
sudo ufw allow 7687
sudo ufw allow 11434

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=7474/tcp
sudo firewall-cmd --permanent --add-port=7687/tcp
sudo firewall-cmd --permanent --add-port=11434/tcp
sudo firewall-cmd --reload

🔒 Security Notes

Default Credentials

  • Neo4j: Username neo4j, Password docuchat123
  • Ollama: No authentication (local access only)

Production Deployment

For production use, consider:

  1. Change default Neo4j password
  2. Enable HTTPS for Neo4j
  3. Configure firewall rules
  4. Use environment variables for secrets
  5. Regular security updates

📚 Advanced Configuration

Custom Neo4j Configuration

Create data/neo4j/conf/neo4j.conf for custom settings:

# Increase memory for large datasets
dbms.memory.heap.initial_size=2G
dbms.memory.heap.max_size=4G

# Enable query logging
dbms.logs.query.enabled=true

Custom Python Dependencies

Add extra packages to requirements-local.txt:

# Your additional dependencies
jupyter>=1.0.0
matplotlib>=3.5.0

Then install: pip install -r requirements-local.txt

Environment Variables

Create .env file for custom configuration:

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=docuchat123

# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434

# Data Paths
DATA_DIR=./data
CHROMA_PATH=./chroma

🤝 Getting Help

If you encounter issues not covered here:

  1. Check the logs: setup_docuchat.log
  2. Run diagnostics: python -m docuchat status --check-all
  3. Search documentation: Check docs/ directory
  4. Report issues: GitHub Issues (include logs and system info)

🔄 Updating

To update DocuChat Agent:

# Pull latest changes
git pull

# Update Python dependencies
source venv/bin/activate
pip install -r requirements.txt --upgrade

# Restart services if needed
docker restart docuchat-neo4j

Ready to get started? Run the setup script and start exploring your documents with AI! 🚀