Add combined FalkorDB + MCP server Docker image

- Created Dockerfile.falkordb-combined extending official FalkorDB image - Added startup script to run both FalkorDB daemon and MCP server - Created docker-compose-falkordb-combined.yml for simplified deployment - Added comprehensive README-falkordb-combined.md documentation - Updated main README with Option 4 for combined image - Single container solution for development and single-node deployments
2025-10-30 12:59:09 -07:00 · 2025-10-30 12:59:09 -07:00 · 44472e22e0
commit 44472e22e0
parent 4b6c81b6ff
4 changed files with 415 additions and 2 deletions
--- a/mcp_server/README.md
+++ b/mcp_server/README.md
@ -392,9 +392,9 @@ Default Neo4j credentials:
 - Bolt URI: `bolt://neo4j:7687`
 - Browser UI: `http://localhost:7474`

-##### Option 3: FalkorDB Database
+##### Option 3: FalkorDB Database (Separate Containers)

-Includes a FalkorDB container (Redis-based graph database):
+Includes separate FalkorDB and MCP server containers:

 ```bash
 docker compose -f docker/docker-compose-falkordb.yml up
@ -405,6 +405,22 @@ FalkorDB configuration:
 - Web UI: `http://localhost:3000`
 - Connection: `redis://falkordb:6379`

+##### Option 4: FalkorDB + MCP Server (Combined Image)
+
+Single container with both FalkorDB and MCP server bundled together:
+
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml up
+```
+
+This combined setup offers:
+- Simplified deployment (one container to manage)
+- Reduced network latency (localhost communication)
+- Easier development workflow
+- Unified logging via Supervisor
+
+See [docker/README-falkordb-combined.md](docker/README-falkordb-combined.md) for detailed documentation.
+
 #### Accessing the MCP Server

 Once running, the MCP server is available at:
--- a/mcp_server/docker/Dockerfile.falkordb-combined
+++ b/mcp_server/docker/Dockerfile.falkordb-combined
@ -0,0 +1,116 @@
+# syntax=docker/dockerfile:1.9
+# Combined FalkorDB + Graphiti MCP Server Image
+# This extends the official FalkorDB image to include the MCP server
+
+FROM falkordb/falkordb:latest AS falkordb-base
+
+# Install Python and system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.12 \
+    python3.12-dev \
+    python3-pip \
+    curl \
+    ca-certificates \
+    procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for Python package management
+ADD https://astral.sh/uv/install.sh /uv-installer.sh
+RUN sh /uv-installer.sh && rm /uv-installer.sh
+
+# Add uv to PATH
+ENV PATH="/root/.local/bin:${PATH}"
+
+# Configure uv for optimal Docker usage
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    MCP_SERVER_HOST="0.0.0.0" \
+    PYTHONUNBUFFERED=1
+
+# Set up MCP server directory
+WORKDIR /app/mcp
+
+# Accept graphiti-core version as build argument
+ARG GRAPHITI_CORE_VERSION=0.22.0
+
+# Copy project files for dependency installation
+COPY pyproject.toml uv.lock ./
+
+# Remove the local path override for graphiti-core in Docker builds
+RUN sed -i '/\[tool\.uv\.sources\]/,/graphiti-core/d' pyproject.toml && \
+    if [ -n "${GRAPHITI_CORE_VERSION}" ]; then \
+      sed -i "s/graphiti-core\[kuzu,falkordb\]>=0\.16\.0/graphiti-core[kuzu,falkordb]==${GRAPHITI_CORE_VERSION}/" pyproject.toml; \
+    fi
+
+# Install Python dependencies
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev
+
+# Store graphiti-core version
+RUN echo "${GRAPHITI_CORE_VERSION}" > /app/mcp/.graphiti-core-version
+
+# Copy MCP server application code
+COPY main.py ./
+COPY src/ ./src/
+COPY config/ ./config/
+
+# Copy FalkorDB-specific config as default
+COPY config/config-docker-falkordb.yaml /app/mcp/config/config.yaml
+
+# Create log directory
+RUN mkdir -p /var/log/graphiti
+
+# Create startup script that runs both services
+RUN cat > /start-services.sh <<'EOF'
+#!/bin/bash
+set -e
+
+# Start FalkorDB in background
+echo "Starting FalkorDB..."
+redis-server \
+  --loadmodule /FalkorDB/bin/linux-x64-release/src/falkordb.so \
+  --protected-mode no \
+  --bind 0.0.0.0 \
+  --port 6379 \
+  --dir /var/lib/falkordb/data \
+  --daemonize yes
+
+# Wait for FalkorDB to be ready
+echo "Waiting for FalkorDB to be ready..."
+until redis-cli -h localhost -p 6379 ping > /dev/null 2>&1; do
+  echo "FalkorDB not ready yet, waiting..."
+  sleep 1
+done
+echo "FalkorDB is ready!"
+
+# Start MCP server in foreground
+echo "Starting MCP server..."
+cd /app/mcp
+exec /root/.local/bin/uv run main.py
+EOF
+
+RUN chmod +x /start-services.sh
+
+# Add Docker labels with version information
+ARG MCP_SERVER_VERSION=1.0.0rc0
+ARG BUILD_DATE
+ARG VCS_REF
+LABEL org.opencontainers.image.title="FalkorDB + Graphiti MCP Server" \
+      org.opencontainers.image.description="Combined FalkorDB graph database with Graphiti MCP server" \
+      org.opencontainers.image.version="${MCP_SERVER_VERSION}" \
+      org.opencontainers.image.created="${BUILD_DATE}" \
+      org.opencontainers.image.revision="${VCS_REF}" \
+      org.opencontainers.image.vendor="Zep AI" \
+      org.opencontainers.image.source="https://github.com/zep-ai/graphiti" \
+      graphiti.core.version="${GRAPHITI_CORE_VERSION}"
+
+# Expose ports
+EXPOSE 6379 3000 8000
+
+# Health check for both services
+HEALTHCHECK --interval=10s --timeout=5s --start-period=15s --retries=3 \
+    CMD redis-cli -p 6379 ping && curl -f http://localhost:8000/health || exit 1
+
+# Run the startup script
+CMD ["/start-services.sh"]
--- a/mcp_server/docker/README-falkordb-combined.md
+++ b/mcp_server/docker/README-falkordb-combined.md
@ -0,0 +1,238 @@
+# FalkorDB + Graphiti MCP Server Combined Image
+
+This Docker setup bundles FalkorDB (graph database) and the Graphiti MCP Server into a single container image for simplified deployment.
+
+## Overview
+
+The combined image extends the official FalkorDB Docker image to include:
+- **FalkorDB**: Redis-based graph database running on port 6379
+- **FalkorDB Web UI**: Graph visualization interface on port 3000
+- **Graphiti MCP Server**: Knowledge graph API on port 8000
+
+Both services are managed by a startup script that launches FalkorDB as a daemon and the MCP server in the foreground.
+
+## Quick Start
+
+### Using Docker Compose (Recommended)
+
+1. Create a `.env` file in the `mcp_server` directory:
+
+```bash
+# Required
+OPENAI_API_KEY=your_openai_api_key
+
+# Optional
+GRAPHITI_GROUP_ID=main
+SEMAPHORE_LIMIT=10
+FALKORDB_PASSWORD=
+```
+
+2. Start the combined service:
+
+```bash
+cd mcp_server
+docker compose -f docker/docker-compose-falkordb-combined.yml up
+```
+
+3. Access the services:
+   - MCP Server: http://localhost:8000/mcp/
+   - FalkorDB Web UI: http://localhost:3000
+   - FalkorDB (Redis): localhost:6379
+
+### Using Docker Run
+
+```bash
+docker run -d \
+  -p 6379:6379 \
+  -p 3000:3000 \
+  -p 8000:8000 \
+  -e OPENAI_API_KEY=your_key \
+  -e GRAPHITI_GROUP_ID=main \
+  -v falkordb_data:/var/lib/falkordb/data \
+  zepai/graphiti-falkordb:latest
+```
+
+## Building the Image
+
+### Build with Default Version
+
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml build
+```
+
+### Build with Specific Graphiti Version
+
+```bash
+GRAPHITI_CORE_VERSION=0.22.0 docker compose -f docker/docker-compose-falkordb-combined.yml build
+```
+
+### Build Arguments
+
+- `GRAPHITI_CORE_VERSION`: Version of graphiti-core package (default: 0.22.0)
+- `MCP_SERVER_VERSION`: MCP server version tag (default: 1.0.0rc0)
+- `BUILD_DATE`: Build timestamp
+- `VCS_REF`: Git commit hash
+
+## Configuration
+
+### Environment Variables
+
+All environment variables from the standard MCP server are supported:
+
+**Required:**
+- `OPENAI_API_KEY`: OpenAI API key for LLM operations
+
+**Optional:**
+- `GRAPHITI_GROUP_ID`: Namespace for graph data (default: "main")
+- `SEMAPHORE_LIMIT`: Concurrency limit for episode processing (default: 10)
+- `FALKORDB_PASSWORD`: Password for FalkorDB (optional)
+- `FALKORDB_DATABASE`: FalkorDB database name (default: "default_db")
+
+**Other LLM Providers:**
+- `ANTHROPIC_API_KEY`: For Claude models
+- `GOOGLE_API_KEY`: For Gemini models
+- `GROQ_API_KEY`: For Groq models
+
+### Volumes
+
+- `/var/lib/falkordb/data`: Persistent storage for graph data
+- `/var/log/graphiti`: MCP server logs
+
+## Service Management
+
+### View Logs
+
+```bash
+# All logs (both services stdout/stderr)
+docker compose -f docker/docker-compose-falkordb-combined.yml logs -f
+
+# Only container logs
+docker compose -f docker/docker-compose-falkordb-combined.yml logs -f graphiti-falkordb
+```
+
+### Restart Services
+
+```bash
+# Restart entire container (both services)
+docker compose -f docker/docker-compose-falkordb-combined.yml restart
+
+# Check FalkorDB status
+docker compose -f docker/docker-compose-falkordb-combined.yml exec graphiti-falkordb redis-cli ping
+
+# Check MCP server status
+curl http://localhost:8000/health
+```
+
+## Health Checks
+
+The container includes a health check that verifies:
+1. FalkorDB is responding to ping
+2. MCP server health endpoint is accessible
+
+Check health status:
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml ps
+```
+
+## Architecture
+
+### Process Structure
+```
+start-services.sh (PID 1)
+├── redis-server (FalkorDB daemon)
+└── uv run main.py (MCP server - foreground)
+```
+
+The startup script launches FalkorDB as a background daemon, waits for it to be ready, then starts the MCP server in the foreground. When the MCP server stops, the container exits.
+
+### Directory Structure
+```
+/app/mcp/                    # MCP server application
+├── main.py
+├── src/
+├── config/
+│   └── config.yaml          # FalkorDB-specific configuration
+└── .graphiti-core-version   # Installed version info
+
+/var/lib/falkordb/data/      # Persistent graph storage
+/var/log/graphiti/           # MCP server logs
+/start-services.sh           # Startup script
+```
+
+## Benefits of Combined Image
+
+1. **Simplified Deployment**: Single container to manage
+2. **Reduced Network Latency**: Localhost communication between services
+3. **Easier Development**: One command to start entire stack
+4. **Unified Logging**: All logs available via docker logs
+5. **Resource Efficiency**: Shared base image and dependencies
+
+## Troubleshooting
+
+### FalkorDB Not Starting
+
+Check container logs:
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml logs graphiti-falkordb
+```
+
+### MCP Server Connection Issues
+
+1. Verify FalkorDB is running:
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml exec graphiti-falkordb redis-cli ping
+```
+
+2. Check MCP server health:
+```bash
+curl http://localhost:8000/health
+```
+
+3. View all container logs:
+```bash
+docker compose -f docker/docker-compose-falkordb-combined.yml logs -f
+```
+
+### Port Conflicts
+
+If ports 6379, 3000, or 8000 are already in use, modify the port mappings in `docker-compose-falkordb-combined.yml`:
+
+```yaml
+ports:
+  - "16379:6379"  # Use different external port
+  - "13000:3000"
+  - "18000:8000"
+```
+
+## Production Considerations
+
+1. **Resource Limits**: Add resource constraints in docker-compose:
+```yaml
+deploy:
+  resources:
+    limits:
+      cpus: '2'
+      memory: 4G
+```
+
+2. **Persistent Volumes**: Use named volumes or bind mounts for production data
+3. **Monitoring**: Export logs to external monitoring system
+4. **Backups**: Regular backups of `/var/lib/falkordb/data` volume
+5. **Security**: Set `FALKORDB_PASSWORD` in production environments
+
+## Comparison with Separate Containers
+
+| Aspect | Combined Image | Separate Containers |
+|--------|---------------|---------------------|
+| Setup Complexity | Simple (one container) | Moderate (service dependencies) |
+| Network Latency | Lower (localhost) | Higher (container network) |
+| Resource Usage | Lower (shared base) | Higher (separate images) |
+| Scalability | Limited | Better (scale independently) |
+| Debugging | Harder (multiple processes) | Easier (isolated services) |
+| Production Use | Development/Single-node | Recommended |
+
+## See Also
+
+- [Main MCP Server README](../README.md)
+- [FalkorDB Documentation](https://docs.falkordb.com/)
+- [Docker Compose Documentation](https://docs.docker.com/compose/)
--- a/mcp_server/docker/docker-compose-falkordb-combined.yml
+++ b/mcp_server/docker/docker-compose-falkordb-combined.yml
@ -0,0 +1,43 @@
+services:
+  graphiti-falkordb:
+    image: zepai/graphiti-falkordb:latest
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.falkordb-combined
+      args:
+        GRAPHITI_CORE_VERSION: ${GRAPHITI_CORE_VERSION:-0.22.0}
+        MCP_SERVER_VERSION: ${MCP_SERVER_VERSION:-1.0.0rc0}
+        BUILD_DATE: ${BUILD_DATE:-}
+        VCS_REF: ${VCS_REF:-}
+    env_file:
+      - path: ../.env
+        required: false
+    environment:
+      # FalkorDB configuration
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+      # MCP Server configuration
+      - FALKORDB_URI=redis://localhost:6379
+      - FALKORDB_DATABASE=${FALKORDB_DATABASE:-default_db}
+      - GRAPHITI_GROUP_ID=${GRAPHITI_GROUP_ID:-main}
+      - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10}
+      - CONFIG_PATH=/app/mcp/config/config.yaml
+      - PATH=/root/.local/bin:${PATH}
+    volumes:
+      - falkordb_data:/var/lib/falkordb/data
+      - mcp_logs:/var/log/graphiti
+    ports:
+      - "6379:6379"  # FalkorDB/Redis
+      - "3000:3000"  # FalkorDB web UI
+      - "8000:8000"  # MCP server HTTP
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli -p 6379 ping && curl -f http://localhost:8000/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+volumes:
+  falkordb_data:
+    driver: local
+  mcp_logs:
+    driver: local