Summary

The official zepai/graphiti:latest Docker image does not support FalkorDB deployment despite the documentation showing FalkorDB as a supported backend. The image only supports Neo4j and fails to start when FalkorDB environment variables are provided.

Problem Description

Expected Behavior

According to the official FalkorDB documentation at https://github.com/getzep/graphiti/blob/main/README.md, Graphiti should support FalkorDB with the following configuration:

# Install with FalkorDB support
pip install graphiti-core[falkordb]

# Environment variables
export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
export OPENAI_API_KEY=your_key

Actual Behavior

When attempting to deploy using the official Docker image zepai/graphiti:latest with FalkorDB configuration, the container fails to start with validation errors.

Steps to Reproduce

1. Deploy FalkorDB container (working correctly):

   docker run -d --name falkordb \
     -p 6379:6379 -p 3000:3000 \
     --restart unless-stopped \
     falkordb/falkordb:latest

2. Create Graphiti server configuration:

   # .env file
   FALKORDB_HOST=host.docker.internal
   FALKORDB_PORT=6379
   FALKORDB_DATABASE=my_knowledge_graph
   OPENAI_API_KEY=your_openai_api_key
   MODEL_NAME=gpt-4o-mini
   GROUP_ID=test_falkordb

3. Create docker-compose.yml:

   version: '3.8'
   services:
     graphiti-api:
       image: zepai/graphiti:latest
       ports:
         - '8000:8000'
       env_file:
         - .env

4. Deploy Graphiti container:

   docker-compose up -d

Error Details

The container exits with code 3 and produces the following error logs:

ERROR:    Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/starlette/routing.py", line 692, in lifespan
    async with self.lifespan_context(app) as maybe_state:
  File "/usr/local/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan
    async with original_context(app) as maybe_original_state:
  File "/usr/local/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan
    async with original_context(app) as maybe_original_state:
  File "/app/graph_service/main.py", line 13, in lifespan
    settings = get_settings()
  File "/app/graph_service/config.py", line 23, in get_settings
    return Settings()
  File "/usr/local/lib/python3.12/site-packages/pydantic_settings/main.py", line 176, in __init__
    super().__init__(
  File "/usr/local/lib/python3.12/site-packages/pydantic/main.py", line 214, in __init__
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
pydantic_core._pydantic_core.ValidationError: 3 validation errors for Settings
neo4j_uri
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]
neo4j_user
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]
neo4j_password
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]

Root Cause Analysis

The official Docker image zepai/graphiti:latest contains server code that:

1. Only supports Neo4j: The Settings class in /app/graph_service/config.py requires neo4j_uri, neo4j_user, and neo4j_password fields
2. Doesn't support FalkorDB: No FalkorDB environment variables are recognized
3. Mismatch with documentation: The documentation shows FalkorDB support, but the Docker image doesn't implement it

Impact

• Users cannot deploy Graphiti with FalkorDB using the official Docker image
• Documentation is misleading - suggests FalkorDB support exists in Docker deployment
• Requires custom builds - users must build their own Docker images to use FalkorDB
• Blocks production deployments - FalkorDB users cannot use the official deployment method

Suggested Solutions

Option 1: Update Official Docker Image

Update the zepai/graphiti:latest image to support both Neo4j and FalkorDB backends by:

• Adding FalkorDB environment variables to the Settings class
• Implementing conditional logic to use FalkorDriver or Neo4jDriver based on configuration
• Maintaining backward compatibility with existing Neo4j deployments

Option 2: Create FalkorDB-Specific Image

Create a separate zepai/graphiti-falkordb:latest image specifically for FalkorDB deployments.

Option 3: Update Documentation

If FalkorDB support is not planned for the Docker image, update the documentation to clarify that:

• FalkorDB support is only available for local Python installations
• Docker deployments require Neo4j backend
• Custom Docker builds are needed for FalkorDB

Environment Information

• FalkorDB Version: falkordb/falkordb:latest (FalkorDB v4.10.3 on Redis 7.4.2)
• Graphiti Docker Image: zepai/graphiti:latest
• Deployment Method: Docker Compose
• Operating System: Ubuntu (Docker host)
• Docker Version: Latest

Additional Context

This issue was discovered while following the official FalkorDB deployment instructions exactly. The FalkorDB container works perfectly, but the Graphiti API server cannot connect to it due to the missing FalkorDB support in the official Docker image.

Related Issues

This appears to be a gap between the documented FalkorDB support and the actual Docker image implementation. Users who want to use FalkorDB with Graphiti currently have no official Docker deployment option.

Priority: High - This blocks FalkorDB users from using the official deployment method
Labels: bug, docker, falkordb, deployment, documentation