From f1536faff84c4a76064f56411b09654635fe664e Mon Sep 17 00:00:00 2001 From: Daniel Chalef <131175+danielchalef@users.noreply.github.com> Date: Sat, 30 Aug 2025 08:46:33 -0700 Subject: [PATCH] refactor: Reorganize Docker Compose files by database type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- mcp_server/config/config-docker-falkordb.yaml | 90 +++++++++ mcp_server/config/config-docker-neo4j.yaml | 92 ++++++++++ mcp_server/docker/README.md | 173 ++++++++++++++++++ ...e-kuzu.yml => docker-compose-falkordb.yml} | 32 +++- mcp_server/docker/docker-compose-neo4j.yml | 64 +++++++ mcp_server/docker/docker-compose.yml | 40 +--- 6 files changed, 452 insertions(+), 39 deletions(-) create mode 100644 mcp_server/config/config-docker-falkordb.yaml create mode 100644 mcp_server/config/config-docker-neo4j.yaml create mode 100644 mcp_server/docker/README.md rename mcp_server/docker/{docker-compose-kuzu.yml => docker-compose-falkordb.yml} (65%) create mode 100644 mcp_server/docker/docker-compose-neo4j.yml diff --git a/mcp_server/config/config-docker-falkordb.yaml b/mcp_server/config/config-docker-falkordb.yaml new file mode 100644 index 00000000..5bc698e8 --- /dev/null +++ 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" \ No newline at end of file diff --git a/mcp_server/config/config-docker-neo4j.yaml b/mcp_server/config/config-docker-neo4j.yaml new file mode 100644 index 00000000..5de08df7 --- /dev/null +++ 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" \ No newline at end of file diff --git a/mcp_server/docker/README.md b/mcp_server/docker/README.md new file mode 100644 index 00000000..ce1929c7 --- /dev/null +++ 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) \ No newline at end of file diff --git a/mcp_server/docker/docker-compose-kuzu.yml b/mcp_server/docker/docker-compose-falkordb.yml similarity index 65% rename from mcp_server/docker/docker-compose-kuzu.yml rename to mcp_server/docker/docker-compose-falkordb.yml index 84ad72a7..c6687509 100644 --- a/mcp_server/docker/docker-compose-kuzu.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 \ No newline at end of file diff --git a/mcp_server/docker/docker-compose-neo4j.yml b/mcp_server/docker/docker-compose-neo4j.yml new file mode 100644 index 00000000..0b3eda0c --- /dev/null +++ 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: diff --git a/mcp_server/docker/docker-compose.yml b/mcp_server/docker/docker-compose.yml index b400e867..84ad72a7 100644 --- 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 \ No newline at end of file