diff --git a/mcp_server/README.md b/mcp_server/README.md index cc936e38..0faa2968 100644 --- 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: diff --git a/mcp_server/docker/Dockerfile.falkordb-combined b/mcp_server/docker/Dockerfile.falkordb-combined new file mode 100644 index 00000000..af2f8a45 --- /dev/null +++ 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"] diff --git a/mcp_server/docker/README-falkordb-combined.md b/mcp_server/docker/README-falkordb-combined.md new file mode 100644 index 00000000..6ed33e8e --- /dev/null +++ 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/) diff --git a/mcp_server/docker/docker-compose-falkordb-combined.yml b/mcp_server/docker/docker-compose-falkordb-combined.yml new file mode 100644 index 00000000..e2c204b9 --- /dev/null +++ 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