refactor: Reorganize Docker Compose files by database type

- Rename docker-compose.yml to docker-compose-neo4j.yml for Neo4j setup - Rename docker-compose-kuzu.yml to docker-compose.yml (making KuzuDB default) - Create docker-compose-falkordb.yml for FalkorDB deployment - Add dedicated config files for each database type: - config-docker-neo4j.yaml for Neo4j - config-docker-falkordb.yaml for FalkorDB - config-docker-kuzu.yaml for KuzuDB - Create comprehensive Docker README with database comparison - Update all compose files to use their respective config files KuzuDB is now the default database for Docker deployments due to: - No external dependencies required - Lower resource usage - Instant startup time - Simpler deployment 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-30 08:46:33 -07:00 · 2025-08-30 08:46:33 -07:00 · f1536faff8
commit f1536faff8
parent fb2ebeba50
6 changed files with 452 additions and 39 deletions
--- a/mcp_server/config/config-docker-falkordb.yaml
+++ b/mcp_server/config/config-docker-falkordb.yaml
@ -0,0 +1,90 @@
+# Graphiti MCP Server Configuration for Docker with FalkorDB
+# This configuration is optimized for running with docker-compose-falkordb.yml
+
+server:
+  transport: "sse"  # SSE for HTTP access from Docker
+  host: "0.0.0.0"
+  port: 8000
+  
+llm:
+  provider: "openai"  # Options: openai, azure_openai, anthropic, gemini, groq
+  model: "gpt-4o"
+  temperature: 0.0
+  max_tokens: 4096
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    anthropic:
+      api_key: ${ANTHROPIC_API_KEY}
+      api_url: ${ANTHROPIC_API_URL:https://api.anthropic.com}
+      max_retries: 3
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    groq:
+      api_key: ${GROQ_API_KEY}
+      api_url: ${GROQ_API_URL:https://api.groq.com/openai/v1}
+
+embedder:
+  provider: "openai"  # Options: openai, azure_openai, gemini, voyage
+  model: "text-embedding-ada-002"
+  dimensions: 1536
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    voyage:
+      api_key: ${VOYAGE_API_KEY}
+      api_url: ${VOYAGE_API_URL:https://api.voyageai.com/v1}
+      model: "voyage-3"
+
+database:
+  provider: "falkordb"  # Using FalkorDB for this configuration
+  
+  providers:
+    falkordb:
+      # Use environment variable if set, otherwise use Docker service hostname
+      uri: ${FALKORDB_URI:redis://falkordb:6379}
+      password: ${FALKORDB_PASSWORD:}
+      database: ${FALKORDB_DATABASE:default_db}
+
+graphiti:
+  group_id: ${GRAPHITI_GROUP_ID:main}
+  episode_id_prefix: ${EPISODE_ID_PREFIX:}
+  user_id: ${USER_ID:mcp_user}
+  entity_types:
+    - name: "Requirement"
+      description: "Represents a requirement"
+    - name: "Preference"
+      description: "User preferences and settings"
+    - name: "Procedure"
+      description: "Standard operating procedures"
--- a/mcp_server/config/config-docker-neo4j.yaml
+++ b/mcp_server/config/config-docker-neo4j.yaml
@ -0,0 +1,92 @@
+# Graphiti MCP Server Configuration for Docker with Neo4j
+# This configuration is optimized for running with docker-compose-neo4j.yml
+
+server:
+  transport: "sse"  # SSE for HTTP access from Docker
+  host: "0.0.0.0"
+  port: 8000
+  
+llm:
+  provider: "openai"  # Options: openai, azure_openai, anthropic, gemini, groq
+  model: "gpt-4o"
+  temperature: 0.0
+  max_tokens: 4096
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    anthropic:
+      api_key: ${ANTHROPIC_API_KEY}
+      api_url: ${ANTHROPIC_API_URL:https://api.anthropic.com}
+      max_retries: 3
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    groq:
+      api_key: ${GROQ_API_KEY}
+      api_url: ${GROQ_API_URL:https://api.groq.com/openai/v1}
+
+embedder:
+  provider: "openai"  # Options: openai, azure_openai, gemini, voyage
+  model: "text-embedding-ada-002"
+  dimensions: 1536
+  
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+      
+    azure_openai:
+      api_key: ${AZURE_OPENAI_API_KEY}
+      api_url: ${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      api_version: ${AZURE_OPENAI_API_VERSION:2024-10-21}
+      deployment_name: ${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      use_azure_ad: ${USE_AZURE_AD:false}
+      
+    gemini:
+      api_key: ${GOOGLE_API_KEY}
+      project_id: ${GOOGLE_PROJECT_ID:}
+      location: ${GOOGLE_LOCATION:us-central1}
+      
+    voyage:
+      api_key: ${VOYAGE_API_KEY}
+      api_url: ${VOYAGE_API_URL:https://api.voyageai.com/v1}
+      model: "voyage-3"
+
+database:
+  provider: "neo4j"  # Using Neo4j for this configuration
+  
+  providers:
+    neo4j:
+      # Use environment variable if set, otherwise use Docker service hostname
+      uri: ${NEO4J_URI:bolt://neo4j:7687}
+      username: ${NEO4J_USER:neo4j}
+      password: ${NEO4J_PASSWORD:demodemo}
+      database: ${NEO4J_DATABASE:neo4j}
+      use_parallel_runtime: ${USE_PARALLEL_RUNTIME:false}
+
+graphiti:
+  group_id: ${GRAPHITI_GROUP_ID:main}
+  episode_id_prefix: ${EPISODE_ID_PREFIX:}
+  user_id: ${USER_ID:mcp_user}
+  entity_types:
+    - name: "Requirement"
+      description: "Represents a requirement"
+    - name: "Preference"
+      description: "User preferences and settings"
+    - name: "Procedure"
+      description: "Standard operating procedures"
--- a/mcp_server/docker/README.md
+++ b/mcp_server/docker/README.md
@ -0,0 +1,173 @@
+# Docker Deployment for Graphiti MCP Server
+
+This directory contains Docker Compose configurations for running the Graphiti MCP server with different database backends.
+
+## Quick Start
+
+The default configuration uses **KuzuDB** (embedded, no external dependencies):
+
+```bash
+docker-compose up
+```
+
+## Database Options
+
+### KuzuDB (Default) - Recommended
+**File:** `docker-compose.yml`
+
+Embedded graph database with persistent storage, no external dependencies.
+
+```bash
+docker-compose up
+```
+
+**Pros:**
+- No external database required
+- Fast startup
+- Low resource usage
+- Single file persistence
+
+**Cons:**
+- Less mature than Neo4j
+- Limited tooling
+
+### Neo4j
+**File:** `docker-compose-neo4j.yml`
+
+Full-featured graph database with web interface.
+
+```bash
+docker-compose -f docker-compose-neo4j.yml up
+```
+
+**Pros:**
+- Mature, battle-tested
+- Rich query language (Cypher)
+- Web UI at http://localhost:7474
+- Extensive tooling
+
+**Cons:**
+- Requires separate database container
+- Higher resource usage (512MB+ RAM)
+- Slower startup (30+ seconds)
+
+### FalkorDB
+**File:** `docker-compose-falkordb.yml`
+
+Redis-based graph database with high performance.
+
+```bash
+docker-compose -f docker-compose-falkordb.yml up
+```
+
+**Pros:**
+- Fast performance
+- Redis-compatible
+- Good for high throughput
+
+**Cons:**
+- Requires separate database container
+- Less tooling than Neo4j
+
+## Environment Variables
+
+Create a `.env` file in this directory:
+
+```bash
+# Required for all configurations
+OPENAI_API_KEY=your-api-key-here
+
+# Optional
+GRAPHITI_GROUP_ID=main
+SEMAPHORE_LIMIT=10
+
+# Database-specific (if using non-default values)
+NEO4J_PASSWORD=yourpassword
+FALKORDB_PASSWORD=yourpassword
+```
+
+## Switching Between Databases
+
+To switch from one database to another:
+
+1. Stop the current setup:
+   ```bash
+   docker-compose down  # or docker-compose -f docker-compose-[db].yml down
+   ```
+
+2. Start with the new database:
+   ```bash
+   docker-compose -f docker-compose-[neo4j|falkordb].yml up
+   ```
+
+Note: Data is not automatically migrated between different database types.
+
+## Data Persistence
+
+All configurations use Docker volumes for data persistence:
+
+- **KuzuDB**: `kuzu_data` volume
+- **Neo4j**: `neo4j_data` and `neo4j_logs` volumes  
+- **FalkorDB**: `falkordb_data` volume
+
+### Backup and Restore
+
+**Backup:**
+```bash
+# Replace [volume_name] with the appropriate volume
+docker run --rm -v [volume_name]:/data -v $(pwd):/backup alpine \
+  tar czf /backup/backup.tar.gz -C /data .
+```
+
+**Restore:**
+```bash
+docker run --rm -v [volume_name]:/data -v $(pwd):/backup alpine \
+  tar xzf /backup/backup.tar.gz -C /data
+```
+
+### Clear Data
+
+To completely reset a database:
+
+```bash
+# Stop containers
+docker-compose -f docker-compose-[db].yml down
+
+# Remove volume
+docker volume rm docker_[volume_name]
+
+# Restart (creates fresh volume)
+docker-compose -f docker-compose-[db].yml up
+```
+
+## Performance Comparison
+
+| Database | Startup Time | Memory Usage | External Container | Best For |
+|----------|-------------|--------------|-------------------|----------|
+| KuzuDB | Instant | ~100MB | No | Development, embedded use |
+| Neo4j | 30+ sec | ~512MB+ | Yes | Production, complex queries |
+| FalkorDB | ~5 sec | ~200MB | Yes | High throughput, caching |
+
+## Troubleshooting
+
+### Port Conflicts
+If port 8000 is already in use:
+```bash
+lsof -i :8000  # Find what's using the port
+```
+
+### Database Connection Issues
+- **KuzuDB**: Check volume permissions
+- **Neo4j**: Wait for health check, check logs
+- **FalkorDB**: Ensure Redis is responding
+
+### API Key Issues
+Verify your `.env` file contains valid API keys:
+```bash
+cat .env | grep API_KEY
+```
+
+## Additional Documentation
+
+- [KuzuDB Setup Guide](README-kuzu.md)
+- [Main MCP Server Documentation](../docs/README.md)
--- a/mcp_server/docker/docker-compose-falkordb.yml
+++ b/mcp_server/docker/docker-compose-falkordb.yml
@ -1,4 +1,19 @@
 services:
+  falkordb:
+    image: falkordb/falkordb:latest
+    ports:
+      - "6379:6379" # Redis/FalkorDB port
+    environment:
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+    volumes:
+      - falkordb_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
  graphiti-mcp:
    image: zepai/knowledge-graph-mcp:latest
    build:
@ -7,10 +22,14 @@ services:
    env_file:
      - path: .env
        required: false # Makes the file optional. Default value is 'true'
+    depends_on:
+      falkordb:
+        condition: service_healthy
    environment:
-      # Database configuration for KuzuDB - using persistent storage
-      - KUZU_DB=${KUZU_DB:-/data/graphiti.kuzu}
-      - KUZU_MAX_CONCURRENT_QUERIES=${KUZU_MAX_CONCURRENT_QUERIES:-10}
+      # Database configuration
+      - FALKORDB_URI=${FALKORDB_URI:-redis://falkordb:6379}
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+      - FALKORDB_DATABASE=${FALKORDB_DATABASE:-default_db}
      # LLM provider configurations
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
@ -29,14 +48,11 @@ services:
      - CONFIG_PATH=/app/config/config.yaml
      - PATH=/root/.local/bin:${PATH}
    volumes:
-      - ../config/config-docker-kuzu.yaml:/app/config/config.yaml:ro
-      # Persistent KuzuDB data storage
-      - kuzu_data:/data
+      - ../config/config-docker-falkordb.yaml:/app/config/config.yaml:ro
    ports:
      - "8000:8000" # Expose the MCP server via HTTP for SSE transport
    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]

-# Volume for persistent KuzuDB storage
 volumes:
-  kuzu_data:
+  falkordb_data:
    driver: local
--- a/mcp_server/docker/docker-compose-neo4j.yml
+++ b/mcp_server/docker/docker-compose-neo4j.yml
@ -0,0 +1,64 @@
+services:
+  neo4j:
+    image: neo4j:5.26.0
+    ports:
+      - "7474:7474" # HTTP
+      - "7687:7687" # Bolt
+    environment:
+      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-demodemo}
+      - NEO4J_server_memory_heap_initial__size=512m
+      - NEO4J_server_memory_heap_max__size=1G
+      - NEO4J_server_memory_pagecache_size=512m
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+    healthcheck:
+      test: ["CMD", "wget", "-O", "/dev/null", "http://localhost:7474"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  graphiti-mcp:
+    image: zepai/knowledge-graph-mcp:latest
+    build:
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - path: .env
+        required: false # Makes the file optional. Default value is 'true'
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    environment:
+      # Database configuration
+      - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
+      - NEO4J_USER=${NEO4J_USER:-neo4j}
+      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
+      - NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j}
+      # LLM provider configurations
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+      - GROQ_API_KEY=${GROQ_API_KEY}
+      - AZURE_OPENAI_API_KEY=${AZURE_OPENAI_API_KEY}
+      - AZURE_OPENAI_ENDPOINT=${AZURE_OPENAI_ENDPOINT}
+      - AZURE_OPENAI_DEPLOYMENT=${AZURE_OPENAI_DEPLOYMENT}
+      # Embedder provider configurations
+      - VOYAGE_API_KEY=${VOYAGE_API_KEY}
+      - AZURE_OPENAI_EMBEDDINGS_ENDPOINT=${AZURE_OPENAI_EMBEDDINGS_ENDPOINT}
+      - AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=${AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT}
+      # Application configuration
+      - GRAPHITI_GROUP_ID=${GRAPHITI_GROUP_ID:-main}
+      - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10}
+      - CONFIG_PATH=/app/config/config.yaml
+      - PATH=/root/.local/bin:${PATH}
+    volumes:
+      - ../config/config-docker-neo4j.yaml:/app/config/config.yaml:ro
+    ports:
+      - "8000:8000" # Expose the MCP server via HTTP for SSE transport
+    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]
+
+volumes:
+  neo4j_data:
+  neo4j_logs:
--- a/mcp_server/docker/docker-compose.yml
+++ b/mcp_server/docker/docker-compose.yml
@ -1,24 +1,4 @@
 services:
-  neo4j:
-    image: neo4j:5.26.0
-    ports:
-      - "7474:7474" # HTTP
-      - "7687:7687" # Bolt
-    environment:
-      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-demodemo}
-      - NEO4J_server_memory_heap_initial__size=512m
-      - NEO4J_server_memory_heap_max__size=1G
-      - NEO4J_server_memory_pagecache_size=512m
-    volumes:
-      - neo4j_data:/data
-      - neo4j_logs:/logs
-    healthcheck:
-      test: ["CMD", "wget", "-O", "/dev/null", "http://localhost:7474"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-
  graphiti-mcp:
    image: zepai/knowledge-graph-mcp:latest
    build:
@ -27,15 +7,10 @@ services:
    env_file:
      - path: .env
        required: false # Makes the file optional. Default value is 'true'
-    depends_on:
-      neo4j:
-        condition: service_healthy
    environment:
-      # Database configuration
-      - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
-      - NEO4J_USER=${NEO4J_USER:-neo4j}
-      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
-      - NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j}
+      # Database configuration for KuzuDB - using persistent storage
+      - KUZU_DB=${KUZU_DB:-/data/graphiti.kuzu}
+      - KUZU_MAX_CONCURRENT_QUERIES=${KUZU_MAX_CONCURRENT_QUERIES:-10}
      # LLM provider configurations
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
@ -54,11 +29,14 @@ services:
      - CONFIG_PATH=/app/config/config.yaml
      - PATH=/root/.local/bin:${PATH}
    volumes:
-      - ./config.yaml:/app/config/config.yaml:ro
+      - ../config/config-docker-kuzu.yaml:/app/config/config.yaml:ro
+      # Persistent KuzuDB data storage
+      - kuzu_data:/data
    ports:
      - "8000:8000" # Expose the MCP server via HTTP for SSE transport
    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse", "--config", "/app/config/config.yaml"]

+# Volume for persistent KuzuDB storage
 volumes:
-  neo4j_data:
-  neo4j_logs:
+  kuzu_data:
+    driver: local