gmakstutis/graphiti
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Consolidate Docker READMEs into single comprehensive guide

Browse source 
- Merge README-kuzu.md content into main Docker README.md
- Add complete FalkorDB documentation with configuration and gotchas
- Remove editorializing about which database is 'best' or 'recommended'
- Provide equal treatment for all three databases (KuzuDB, Neo4j, FalkorDB)
- Include specific gotchas and troubleshooting for each database
- Add detailed backup/restore procedures for each database type
- Document all environment variables and configuration options
- Remove pros/cons sections and performance comparison editorializing
- Delete redundant README-kuzu.md file

The documentation now provides factual, unbiased instructions for using
any of the three supported graph databases.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Daniel Chalef 2025-08-30 09:04:34 -07:00
parent 859af2e4d8
commit 057056270a
2 changed files with 269 additions and 245 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

122
mcp_server/docker/README-kuzu.md
View file

@ -1,122 +0,0 @@
# Running MCP Server with KuzuDB
This guide explains how to run the Graphiti MCP server with KuzuDB as the graph database backend using Docker Compose.
## Why KuzuDB?
KuzuDB is an embedded graph database that provides several advantages:
- **No external dependencies**: Unlike Neo4j, KuzuDB runs embedded within the application
- **Persistent storage**: Data is stored in a single file/directory
- **High performance**: Optimized for analytical workloads
- **Low resource usage**: Minimal memory and CPU requirements
## Quick Start
1. **Set up environment variables**:
Create a `.env` file in the `docker` directory:
```bash
OPENAI_API_KEY=your-api-key-here
# Optional: Override default settings
GRAPHITI_GROUP_ID=my-group
KUZU_MAX_CONCURRENT_QUERIES=20
```
2. **Start the server**:
```bash
docker-compose -f docker-compose-kuzu.yml up
```
3. **Access the MCP server**:
The server will be available at `http://localhost:8000`
## Configuration
### Persistent Storage
By default, KuzuDB data is stored in a Docker volume at `/data/graphiti.kuzu`. This ensures your data persists across container restarts.
To use a different location, set the `KUZU_DB` environment variable:
```bash
KUZU_DB=/data/my-custom-db.kuzu
```
### In-Memory Mode
For testing or temporary usage, you can run KuzuDB in memory-only mode:
```bash
KUZU_DB=:memory:
```
Note: Data will be lost when the container stops.
### Performance Tuning
Adjust the maximum number of concurrent queries:
```bash
KUZU_MAX_CONCURRENT_QUERIES=20 # Default is 10
```
## Data Management
### Backup
To backup your KuzuDB data:
```bash
# Create a backup of the volume
docker run --rm -v mcp_server_kuzu_data:/data -v $(pwd):/backup alpine tar czf /backup/kuzu-backup.tar.gz -C /data .
```
### Restore
To restore from a backup:
```bash
# Restore from backup
docker run --rm -v mcp_server_kuzu_data:/data -v $(pwd):/backup alpine tar xzf /backup/kuzu-backup.tar.gz -C /data
```
### Clear Data
To completely clear the KuzuDB data:
```bash
# Stop the container
docker-compose -f docker-compose-kuzu.yml down
# Remove the volume
docker volume rm docker_kuzu_data
# Restart (will create fresh volume)
docker-compose -f docker-compose-kuzu.yml up
```
## Switching from Neo4j
If you're migrating from Neo4j to KuzuDB:
1. Export your data from Neo4j (if needed)
2. Stop the Neo4j-based setup: `docker-compose down`
3. Start the KuzuDB setup: `docker-compose -f docker-compose-kuzu.yml up`
4. Re-import your data through the MCP API
## Troubleshooting
### Container won't start
- Check that port 8000 is not in use: `lsof -i :8000`
- Verify your `.env` file has valid API keys
### Data not persisting
- Ensure the volume is properly mounted: `docker volume ls`
- Check volume permissions: `docker exec graphiti-mcp ls -la /data`
### Performance issues
- Increase `KUZU_MAX_CONCURRENT_QUERIES` for better parallelism
- Monitor container resources: `docker stats graphiti-mcp`
## Comparison with Neo4j Setup
| Feature | KuzuDB | Neo4j |
|---------|--------|-------|
| External Database | No | Yes |
| Memory Usage | Low (~100MB) | High (~512MB min) |
| Startup Time | Instant | 30+ seconds |
| Persistent Storage | Single file | Multiple files |
| Docker Services | 1 | 2 |
| Default Port | 8000 (MCP only) | 8000, 7474, 7687 |

392
mcp_server/docker/README.md
View file

@ -1,173 +1,319 @@
# Docker Deployment for Graphiti MCP Server # Docker Deployment for Graphiti MCP Server
This directory contains Docker Compose configurations for running the Graphiti MCP server with different database backends. This directory contains Docker Compose configurations for running the Graphiti MCP server with different graph database backends: KuzuDB, Neo4j, and FalkorDB.
## Quick Start ## Quick Start
The default configuration uses **KuzuDB** (embedded, no external dependencies):
```bash ```bash
# Default configuration (KuzuDB)
docker-compose up docker-compose up
```
## Database Options # Neo4j
### 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 docker-compose -f docker-compose-neo4j.yml up
```
**Pros:** # FalkorDB
- 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 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 ## Environment Variables
Create a `.env` file in this directory: Create a `.env` file in this directory with your API keys:
```bash ```bash
# Required for all configurations # Required
OPENAI_API_KEY=your-api-key-here OPENAI_API_KEY=your-api-key-here
# Optional # Optional
GRAPHITI_GROUP_ID=main GRAPHITI_GROUP_ID=main
SEMAPHORE_LIMIT=10 SEMAPHORE_LIMIT=10
# Database-specific (if using non-default values) # Database-specific variables (see database sections below)
NEO4J_PASSWORD=yourpassword
FALKORDB_PASSWORD=yourpassword
``` ```
## Database Configurations
### KuzuDB
**File:** `docker-compose.yml` (default)
KuzuDB is an embedded graph database that runs within the application container.
#### Configuration
```bash
# Environment variables
KUZU_DB=/data/graphiti.kuzu # Database file path (default: /data/graphiti.kuzu)
KUZU_MAX_CONCURRENT_QUERIES=10 # Maximum concurrent queries (default: 10)
```
#### Storage Options
**Persistent Storage (default):**
Data is stored in the `kuzu_data` Docker volume at `/data/graphiti.kuzu`.
**In-Memory Mode:**
```bash
KUZU_DB=:memory:
```
Note: Data will be lost when the container stops.
#### Data Management
**Backup:**
```bash
docker run --rm -v docker_kuzu_data:/data -v $(pwd):/backup alpine \
tar czf /backup/kuzu-backup.tar.gz -C /data .
```
**Restore:**
```bash
docker run --rm -v docker_kuzu_data:/data -v $(pwd):/backup alpine \
tar xzf /backup/kuzu-backup.tar.gz -C /data
```
**Clear Data:**
```bash
docker-compose down
docker volume rm docker_kuzu_data
docker-compose up # Creates fresh volume
```
#### Gotchas
- KuzuDB data is stored in a single file/directory
- The database file can grow large with extensive data
- In-memory mode provides faster performance but no persistence
### Neo4j
**File:** `docker-compose-neo4j.yml`
Neo4j runs as a separate container service with its own web interface.
#### Configuration
```bash
# Environment variables
NEO4J_URI=bolt://neo4j:7687 # Connection URI (default: bolt://neo4j:7687)
NEO4J_USER=neo4j # Username (default: neo4j)
NEO4J_PASSWORD=demodemo # Password (default: demodemo)
NEO4J_DATABASE=neo4j # Database name (default: neo4j)
USE_PARALLEL_RUNTIME=false # Enterprise feature (default: false)
```
#### Accessing Neo4j
- **Web Interface:** http://localhost:7474
- **Bolt Protocol:** bolt://localhost:7687
- **MCP Server:** http://localhost:8000
Default credentials: `neo4j` / `demodemo`
#### Data Management
**Backup:**
```bash
# Backup both data and logs volumes
docker run --rm -v docker_neo4j_data:/data -v $(pwd):/backup alpine \
tar czf /backup/neo4j-data-backup.tar.gz -C /data .
docker run --rm -v docker_neo4j_logs:/logs -v $(pwd):/backup alpine \
tar czf /backup/neo4j-logs-backup.tar.gz -C /logs .
```
**Restore:**
```bash
# Restore both volumes
docker run --rm -v docker_neo4j_data:/data -v $(pwd):/backup alpine \
tar xzf /backup/neo4j-data-backup.tar.gz -C /data
docker run --rm -v docker_neo4j_logs:/logs -v $(pwd):/backup alpine \
tar xzf /backup/neo4j-logs-backup.tar.gz -C /logs
```
**Clear Data:**
```bash
docker-compose -f docker-compose-neo4j.yml down
docker volume rm docker_neo4j_data docker_neo4j_logs
docker-compose -f docker-compose-neo4j.yml up
```
#### Gotchas
- Neo4j takes 30+ seconds to start up - wait for the health check
- The web interface requires authentication even for local access
- Memory heap is configured for 512MB initial, 1GB max
- Page cache is set to 512MB
- Enterprise features like parallel runtime require a license
### FalkorDB
**File:** `docker-compose-falkordb.yml`
FalkorDB is a Redis-based graph database that runs as a separate container.
#### Configuration
```bash
# Environment variables
FALKORDB_URI=redis://falkordb:6379 # Connection URI (default: redis://falkordb:6379)
FALKORDB_PASSWORD= # Password (default: empty)
FALKORDB_DATABASE=default_db # Database name (default: default_db)
```
#### Accessing FalkorDB
- **Redis Protocol:** redis://localhost:6379
- **MCP Server:** http://localhost:8000
#### Data Management
**Backup:**
```bash
docker run --rm -v docker_falkordb_data:/data -v $(pwd):/backup alpine \
tar czf /backup/falkordb-backup.tar.gz -C /data .
```
**Restore:**
```bash
docker run --rm -v docker_falkordb_data:/data -v $(pwd):/backup alpine \
tar xzf /backup/falkordb-backup.tar.gz -C /data
```
**Clear Data:**
```bash
docker-compose -f docker-compose-falkordb.yml down
docker volume rm docker_falkordb_data
docker-compose -f docker-compose-falkordb.yml up
```
#### Gotchas
- FalkorDB uses Redis persistence mechanisms (AOF/RDB)
- Default configuration has no password - add one for production
- Database name is created automatically if it doesn't exist
- Redis commands can be used for debugging: `redis-cli -h localhost`
## Switching Between Databases ## Switching Between Databases
To switch from one database to another: To switch from one database to another:
1. Stop the current setup: 1. **Stop current setup:**
```bash ```bash
docker-compose down # or docker-compose -f docker-compose-[db].yml down docker-compose down # or docker-compose -f docker-compose-[db].yml down
``` ```
2. Start with the new database: 2. **Start new database:**
```bash ```bash
docker-compose -f docker-compose-[neo4j|falkordb].yml up docker-compose -f docker-compose-[neo4j|falkordb].yml up
# or just docker-compose up for KuzuDB
``` ```
Note: Data is not automatically migrated between different database types. Note: Data is not automatically migrated between different database types. You'll need to export from one and import to another using the MCP API.
## 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 ## Troubleshooting
### Port Conflicts ### Port Conflicts
If port 8000 is already in use: If port 8000 is already in use:
```bash ```bash
lsof -i :8000 # Find what's using the port # Find what's using the port
lsof -i :8000
# Change the port in docker-compose.yml
# Under ports section: "8001:8000"
``` ```
### Container Won't Start
1. Check logs:
```bash
docker-compose logs graphiti-mcp
```
2. Verify `.env` file exists and contains valid API keys:
```bash
cat .env | grep API_KEY
```
3. Ensure Docker has enough resources allocated
### Database Connection Issues ### Database Connection Issues
- **KuzuDB**: Check volume permissions
- **Neo4j**: Wait for health check, check logs
- **FalkorDB**: Ensure Redis is responding
### API Key Issues **KuzuDB:**
Verify your `.env` file contains valid API keys: - Check volume permissions: `docker exec graphiti-mcp ls -la /data`
```bash - Verify database file isn't corrupted
cat .env | grep API_KEY
**Neo4j:**
- Wait for health check to pass (can take 30+ seconds)
- Check Neo4j logs: `docker-compose -f docker-compose-neo4j.yml logs neo4j`
- Verify credentials match environment variables
**FalkorDB:**
- Test Redis connectivity: `redis-cli -h localhost ping`
- Check FalkorDB logs: `docker-compose -f docker-compose-falkordb.yml logs falkordb`
### Data Not Persisting
1. Verify volumes are created:
```bash
docker volume ls | grep docker_
```
2. Check volume mounts in container:
```bash
docker inspect graphiti-mcp | grep -A 5 Mounts
```
3. Ensure proper shutdown:
```bash
docker-compose down # Not docker-compose down -v (which removes volumes)
```
### Performance Issues
**KuzuDB:**
- Increase `KUZU_MAX_CONCURRENT_QUERIES`
- Consider using SSD for database file storage
- Monitor with: `docker stats graphiti-mcp`
**Neo4j:**
- Increase heap memory in docker-compose-neo4j.yml
- Adjust page cache size based on data size
- Check query performance in Neo4j browser
**FalkorDB:**
- Adjust Redis max memory policy
- Monitor with: `redis-cli -h localhost info memory`
- Consider Redis persistence settings (AOF vs RDB)
## Docker Resources
### Volumes
Each database configuration uses named volumes for data persistence:
- KuzuDB: `kuzu_data`
- Neo4j: `neo4j_data`, `neo4j_logs`
- FalkorDB: `falkordb_data`
### Networks
All configurations use the default bridge network. Services communicate using container names as hostnames.
### Resource Limits
No resource limits are set by default. To add limits, modify the docker-compose file:
```yaml
services:
graphiti-mcp:
deploy:
resources:
limits:
cpus: '2.0'
memory: 1G
``` ```
## Additional Documentation ## Configuration Files
- [KuzuDB Setup Guide](README-kuzu.md) Each database has a dedicated configuration file in `../config/`:
- [Main MCP Server Documentation](../docs/README.md) - `config-docker-kuzu.yaml` - KuzuDB configuration
- `config-docker-neo4j.yaml` - Neo4j configuration
- `config-docker-falkordb.yaml` - FalkorDB configuration
These files are mounted read-only into the container at `/app/config/config.yaml`.