Skip to content

Commit 9e65490

Browse files
claude[bot]phernandez
claude[bot]
and
phernandez
authored
feat: add Docker container support with volume mounting for Obsidian directories
- Add docker-compose.yml with volume mounting for Obsidian vaults - Create comprehensive Docker.md documentation guide - Add docker-compose.examples.yml with 7 different use case examples - Include docker-entrypoint.sh for better configuration management - Update README.md with Docker installation section Addresses feature request from Reddit user wanting to integrate Obsidian directories using Docker volumes with existing MCP server setup. Key features: - Volume mounting support for knowledge directories - Persistent configuration and database storage - Multiple transport options (STDIO/HTTP) - Multi-project support - Health checks and restart policies - Comprehensive documentation and examples Co-authored-by: phernandez <phernandez@users.noreply.github.com>
1 parent ac401ea commit 9e65490

5 files changed

Lines changed: 747 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,31 @@ Development versions are automatically published on every commit to main with ve
394394
pip install basic-memory --pre --force-reinstall
395395
```
396396

397+
### Docker
398+
399+
Run Basic Memory in a container with volume mounting for your Obsidian vault:
400+
401+
```bash
402+
# Clone and start with Docker Compose
403+
git clone https://github.com/basicmachines-co/basic-memory.git
404+
cd basic-memory
405+
406+
# Edit docker-compose.yml to point to your Obsidian vault
407+
# Then start the container
408+
docker-compose up -d
409+
```
410+
411+
Or use Docker directly:
412+
```bash
413+
docker run -d \
414+
--name basic-memory-server \
415+
-v /path/to/your/obsidian-vault:/data/knowledge:rw \
416+
-v basic-memory-config:/root/.basic-memory:rw \
417+
ghcr.io/basicmachines-co/basic-memory:latest
418+
```
419+
420+
See [Docker Setup Guide](docs/Docker.md) for detailed configuration options, multiple project setup, and integration examples.
421+
397422
## License
398423

399424
AGPL-3.0

‎docker-compose.examples.yml‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Example Docker Compose configurations for Basic Memory
2+
# Copy the relevant section to your docker-compose.yml and modify as needed
3+
4+
# ================================================================================
5+
# Example 1: Simple Obsidian Vault Integration
6+
# ================================================================================
7+
version: '3.8'
8+
services:
9+
basic-memory-obsidian:
10+
build: .
11+
container_name: basic-memory-obsidian
12+
volumes:
13+
# Replace with your actual Obsidian vault path
14+
- /Users/yourname/Documents/MyVault:/data/knowledge:rw
15+
- basic-memory-config:/root/.basic-memory:rw
16+
environment:
17+
- BASIC_MEMORY_PROJECTS={"obsidian": "/data/knowledge"}
18+
- BASIC_MEMORY_DEFAULT_PROJECT=obsidian
19+
- BASIC_MEMORY_SYNC_CHANGES=true
20+
command: ["basic-memory", "mcp"]
21+
restart: unless-stopped
22+
23+
volumes:
24+
basic-memory-config:
25+
26+
---
27+
28+
# ================================================================================
29+
# Example 2: Multiple Knowledge Bases
30+
# ================================================================================
31+
version: '3.8'
32+
services:
33+
basic-memory-multi:
34+
build: .
35+
container_name: basic-memory-multi
36+
volumes:
37+
- /path/to/personal-notes:/data/projects/personal:rw
38+
- /path/to/work-notes:/data/projects/work:rw
39+
- /path/to/research:/data/projects/research:rw
40+
- basic-memory-config:/root/.basic-memory:rw
41+
environment:
42+
- BASIC_MEMORY_PROJECTS={"personal": "/data/projects/personal", "work": "/data/projects/work", "research": "/data/projects/research"}
43+
- BASIC_MEMORY_DEFAULT_PROJECT=personal
44+
- BASIC_MEMORY_SYNC_CHANGES=true
45+
command: ["basic-memory", "mcp"]
46+
restart: unless-stopped
47+
48+
volumes:
49+
basic-memory-config:
50+
51+
---
52+
53+
# ================================================================================
54+
# Example 3: HTTP Transport for External Integration
55+
# ================================================================================
56+
version: '3.8'
57+
services:
58+
basic-memory-http:
59+
build: .
60+
container_name: basic-memory-http
61+
volumes:
62+
- ./knowledge:/data/knowledge:rw
63+
- basic-memory-config:/root/.basic-memory:rw
64+
environment:
65+
- BASIC_MEMORY_PROJECTS={"main": "/data/knowledge"}
66+
- BASIC_MEMORY_DEFAULT_PROJECT=main
67+
- BASIC_MEMORY_SYNC_CHANGES=true
68+
ports:
69+
- "8000:8000"
70+
command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
71+
restart: unless-stopped
72+
healthcheck:
73+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
74+
interval: 30s
75+
timeout: 10s
76+
retries: 3
77+
78+
volumes:
79+
basic-memory-config:
80+
81+
---
82+
83+
# ================================================================================
84+
# Example 4: Integration with Existing MCP Server Stack
85+
# ================================================================================
86+
version: '3.8'
87+
services:
88+
# Your existing MCP server
89+
mcp-proxy:
90+
image: your-mcp-server:latest
91+
container_name: mcp-proxy
92+
depends_on:
93+
- basic-memory
94+
networks:
95+
- mcp-network
96+
# ... your MCP server configuration
97+
98+
# Basic Memory as a service
99+
basic-memory:
100+
build: .
101+
container_name: basic-memory-service
102+
volumes:
103+
- ./shared-knowledge:/data/knowledge:rw
104+
- basic-memory-config:/root/.basic-memory:rw
105+
environment:
106+
- BASIC_MEMORY_PROJECTS={"shared": "/data/knowledge"}
107+
- BASIC_MEMORY_DEFAULT_PROJECT=shared
108+
- BASIC_MEMORY_SYNC_CHANGES=true
109+
networks:
110+
- mcp-network
111+
command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
112+
restart: unless-stopped
113+
114+
volumes:
115+
basic-memory-config:
116+
117+
networks:
118+
mcp-network:
119+
driver: bridge
120+
121+
---
122+
123+
# ================================================================================
124+
# Example 5: Development Environment with Debug Logging
125+
# ================================================================================
126+
version: '3.8'
127+
services:
128+
basic-memory-dev:
129+
build: .
130+
container_name: basic-memory-dev
131+
volumes:
132+
- ./dev-knowledge:/data/knowledge:rw
133+
- basic-memory-config:/root/.basic-memory:rw
134+
# Mount source code for development (optional)
135+
# - ./src:/app/src:ro
136+
environment:
137+
- BASIC_MEMORY_PROJECTS={"dev": "/data/knowledge"}
138+
- BASIC_MEMORY_DEFAULT_PROJECT=dev
139+
- BASIC_MEMORY_SYNC_CHANGES=true
140+
- BASIC_MEMORY_LOG_LEVEL=DEBUG
141+
- BASIC_MEMORY_SYNC_DELAY=500 # Faster sync for development
142+
ports:
143+
- "8000:8000"
144+
command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
145+
restart: unless-stopped
146+
147+
volumes:
148+
basic-memory-config:
149+
150+
---
151+
152+
# ================================================================================
153+
# Example 6: Production Deployment with Resource Limits
154+
# ================================================================================
155+
version: '3.8'
156+
services:
157+
basic-memory-prod:
158+
build: .
159+
container_name: basic-memory-prod
160+
volumes:
161+
- /var/data/knowledge:/data/knowledge:rw
162+
- basic-memory-config:/root/.basic-memory:rw
163+
environment:
164+
- BASIC_MEMORY_PROJECTS={"production": "/data/knowledge"}
165+
- BASIC_MEMORY_DEFAULT_PROJECT=production
166+
- BASIC_MEMORY_SYNC_CHANGES=true
167+
- BASIC_MEMORY_LOG_LEVEL=INFO
168+
deploy:
169+
resources:
170+
limits:
171+
memory: 1G
172+
cpus: '1.0'
173+
reservations:
174+
memory: 512M
175+
cpus: '0.5'
176+
healthcheck:
177+
test: ["CMD", "basic-memory", "--version"]
178+
interval: 30s
179+
timeout: 10s
180+
retries: 3
181+
start_period: 60s
182+
restart: unless-stopped
183+
command: ["basic-memory", "mcp"]
184+
185+
volumes:
186+
basic-memory-config:
187+
driver: local
188+
driver_opts:
189+
type: none
190+
o: bind
191+
device: /var/data/basic-memory-config
192+
193+
---
194+
195+
# ================================================================================
196+
# Example 7: Using with External Database (Advanced)
197+
# ================================================================================
198+
version: '3.8'
199+
services:
200+
basic-memory-external-db:
201+
build: .
202+
container_name: basic-memory-external
203+
volumes:
204+
- ./knowledge:/data/knowledge:rw
205+
# Mount external database location
206+
- /external/storage/basic-memory:/root/.basic-memory:rw
207+
environment:
208+
- BASIC_MEMORY_PROJECTS={"main": "/data/knowledge"}
209+
- BASIC_MEMORY_DEFAULT_PROJECT=main
210+
- BASIC_MEMORY_SYNC_CHANGES=true
211+
command: ["basic-memory", "mcp"]
212+
restart: unless-stopped
213+
214+
# Note: No volumes section - using external storage

‎docker-compose.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Docker Compose configuration for Basic Memory
2+
# See docs/Docker.md for detailed setup instructions
3+
4+
version: '3.8'
5+
6+
services:
7+
basic-memory:
8+
build: .
9+
container_name: basic-memory-server
10+
11+
# Volume mounts for knowledge directories and persistent data
12+
volumes:
13+
# REQUIRED: Mount your Obsidian vault or knowledge directory
14+
# Change './obsidian-vault' to your actual directory path
15+
# Example: - /Users/yourname/Documents/ObsidianVault:/data/knowledge:rw
16+
- ./obsidian-vault:/data/knowledge:rw
17+
18+
# RECOMMENDED: Persistent storage for configuration and database
19+
- basic-memory-config:/root/.basic-memory:rw
20+
21+
# OPTIONAL: Mount additional knowledge directories for multiple projects
22+
# - ./work-notes:/data/projects/work:rw
23+
# - ./personal-notes:/data/projects/personal:rw
24+
25+
environment:
26+
# Project configuration - maps project names to container paths
27+
- BASIC_MEMORY_PROJECTS={"main": "/data/knowledge"}
28+
- BASIC_MEMORY_DEFAULT_PROJECT=main
29+
30+
# Enable real-time file synchronization (recommended for Docker)
31+
- BASIC_MEMORY_SYNC_CHANGES=true
32+
33+
# Logging configuration
34+
- BASIC_MEMORY_LOG_LEVEL=INFO
35+
36+
# Sync delay in milliseconds (adjust for performance vs responsiveness)
37+
- BASIC_MEMORY_SYNC_DELAY=1000
38+
39+
# Port exposure for HTTP transport (only needed if not using STDIO)
40+
ports:
41+
- "8000:8000"
42+
43+
# Command options:
44+
45+
# Option 1: STDIO transport (default, recommended for MCP clients)
46+
command: ["basic-memory", "mcp"]
47+
48+
# Option 2: HTTP Server-Sent Events transport (uncomment to use)
49+
# command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
50+
51+
# Option 3: HTTP streamable transport (uncomment to use)
52+
# command: ["basic-memory", "mcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
53+
54+
# Container management
55+
restart: unless-stopped
56+
57+
# Health monitoring
58+
healthcheck:
59+
test: ["CMD", "basic-memory", "--version"]
60+
interval: 30s
61+
timeout: 10s
62+
retries: 3
63+
start_period: 30s
64+
65+
# Optional: Resource limits
66+
# deploy:
67+
# resources:
68+
# limits:
69+
# memory: 512M
70+
# cpus: '0.5'
71+
# reservations:
72+
# memory: 256M
73+
# cpus: '0.25'
74+
75+
volumes:
76+
# Named volume for persistent configuration and database
77+
# This ensures your configuration and knowledge graph persist across container restarts
78+
basic-memory-config:
79+
driver: local
80+
81+
# Network configuration (optional)
82+
# networks:
83+
# basic-memory-net:
84+
# driver: bridge

‎docker-entrypoint.sh‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#!/bin/bash
2+
set -e
3+
4+
# Docker entrypoint script for Basic Memory
5+
# This script helps configure Basic Memory in a containerized environment
6+
7+
echo "Starting Basic Memory Docker container..."
8+
9+
# Create configuration directory if it doesn't exist
10+
mkdir -p /root/.basic-memory
11+
12+
# If no config exists, create a default one with proper project mapping
13+
CONFIG_FILE="/root/.basic-memory/config.json"
14+
if [ ! -f "$CONFIG_FILE" ]; then
15+
echo "Creating default configuration..."
16+
cat > "$CONFIG_FILE" << EOF
17+
{
18+
"env": "user",
19+
"projects": {
20+
"main": "/data/knowledge"
21+
},
22+
"default_project": "main",
23+
"log_level": "INFO",
24+
"sync_delay": 1000,
25+
"update_permalinks_on_move": false,
26+
"sync_changes": true
27+
}
28+
EOF
29+
fi
30+
31+
# Ensure project directories exist
32+
if [ -d "/data/knowledge" ]; then
33+
echo "Knowledge directory found at /data/knowledge"
34+
else
35+
echo "Warning: No knowledge directory mounted at /data/knowledge"
36+
echo "Consider mounting your Obsidian vault with: -v /path/to/your/vault:/data/knowledge"
37+
fi
38+
39+
# Handle additional project directories
40+
for dir in /data/projects/*/; do
41+
if [ -d "$dir" ]; then
42+
project_name=$(basename "$dir")
43+
echo "Found additional project directory: $project_name at $dir"
44+
fi
45+
done
46+
47+
# Show configuration info
48+
echo "Basic Memory Configuration:"
49+
echo "- Config file: $CONFIG_FILE"
50+
echo "- Main project directory: /data/knowledge"
51+
echo "- Database: /root/.basic-memory/memory.db"
52+
echo "- Command: $@"
53+
54+
# Execute the provided command
55+
exec "$@"

0 commit comments

Comments
 (0)