basicmachines-co-basic-memory/docs/Docker.md

# Docker Setup Guide

Basic Memory can be run in Docker containers to provide a consistent, isolated environment for your knowledge management
system. This is particularly useful for integrating with existing Dockerized MCP servers or for deployment scenarios.

## Quick Start

### Option 1: Using Docker Compose (Recommended)

1. **Clone the repository:**
   ```bash
   git clone https://github.com/basicmachines-co/basic-memory.git
   cd basic-memory
   ```

2. **Update the docker-compose.yml:**
   Edit the volume mount to point to your Obsidian vault:
   ```yaml
   volumes:
     # Change './obsidian-vault' to your actual directory path
     - /path/to/your/obsidian-vault:/data/knowledge:rw
   ```

3. **Start the container:**
   ```bash
   docker-compose up -d
   ```

### Option 2: Using Docker CLI

```bash
# Build the image
docker build -t basic-memory .

# Run with volume mounting
docker run -d \
  --name basic-memory-server \
  -v /path/to/your/obsidian-vault:/data/knowledge:rw \
  -v basic-memory-config:/root/.basic-memory:rw \
  -e BASIC_MEMORY_DEFAULT_PROJECT=main \
  basic-memory
```

## Configuration

### Volume Mounts

Basic Memory requires several volume mounts for proper operation:

1. **Knowledge Directory** (Required):
   ```yaml
   - /path/to/your/obsidian-vault:/data/knowledge:rw
   ```
   Mount your Obsidian vault or knowledge base directory.

2. **Configuration and Database** (Recommended):
   ```yaml
   - basic-memory-config:/root/.basic-memory:rw
   ```
   Persistent storage for configuration and SQLite database.

You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json after Basic Memory starts.

3. **Multiple Projects** (Optional):
   ```yaml
   - /path/to/project1:/data/projects/project1:rw
   - /path/to/project2:/data/projects/project2:rw
   ```

You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json

## CLI Commands via Docker

You can run Basic Memory CLI commands inside the container using `docker exec`:

### Basic Commands

```bash
# Check status
docker exec basic-memory-server basic-memory status

# Sync files
docker exec basic-memory-server basic-memory sync

# Show help
docker exec basic-memory-server basic-memory --help
```

### Managing Projects with Volume Mounts

When using Docker volumes, you'll need to configure projects to point to your mounted directories:

1. **Check current configuration:**
   ```bash
   docker exec basic-memory-server cat /root/.basic-memory/config.json
   ```

2. **Add a project for your mounted volume:**
   ```bash
   # If you mounted /path/to/your/vault to /data/knowledge
   docker exec basic-memory-server basic-memory project create my-vault /data/knowledge
   
   # Set it as default
   docker exec basic-memory-server basic-memory project set-default my-vault
   ```

3. **Sync the new project:**
   ```bash
   docker exec basic-memory-server basic-memory sync
   ```

### Example: Setting up an Obsidian Vault

If you mounted your Obsidian vault like this in docker-compose.yml:
```yaml
volumes:
  - /Users/yourname/Documents/ObsidianVault:/data/obsidian:rw
```

Then configure it:
```bash
# Create project pointing to mounted vault
docker exec basic-memory-server basic-memory project create obsidian /data/obsidian

# Set as default
docker exec basic-memory-server basic-memory project set-default obsidian

# Sync to index all files
docker exec basic-memory-server basic-memory sync
```

### Environment Variables

Configure Basic Memory using environment variables:

```yaml
environment:

  # Default project
  - BASIC_MEMORY_DEFAULT_PROJECT=main

  # Enable real-time sync
  - BASIC_MEMORY_SYNC_CHANGES=true

  # Logging level
  - BASIC_MEMORY_LOG_LEVEL=INFO

  # Sync delay in milliseconds
  - BASIC_MEMORY_SYNC_DELAY=1000
```

## File Permissions

### Linux/macOS

Ensure your knowledge directories have proper permissions:

```bash
# Make directories readable/writable
chmod -R 755 /path/to/your/obsidian-vault

# If using specific user/group
chown -R $USER:$USER /path/to/your/obsidian-vault
```

### Windows

When using Docker Desktop on Windows, ensure the directories are shared:

1. Open Docker Desktop
2. Go to Settings → Resources → File Sharing
3. Add your knowledge directory path
4. Apply & Restart

## Troubleshooting

### Common Issues

1. **File Watching Not Working:**
    - Ensure volume mounts are read-write (`:rw`)
    - Check directory permissions
    - On Linux, may need to increase inotify limits:
      ```bash
      echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
      sudo sysctl -p
      ```

2. **Configuration Not Persisting:**
    - Use named volumes for `/root/.basic-memory`
    - Check volume mount permissions

3. **Network Connectivity:**
    - For HTTP transport, ensure port 8000 is exposed
    - Check firewall settings

### Debug Mode

Run with debug logging:

```yaml
environment:
  - BASIC_MEMORY_LOG_LEVEL=DEBUG
```

View logs:

```bash
docker-compose logs -f basic-memory
```


## Security Considerations

1. **Use Non-Root User:**
   The default Dockerfile runs as root. Consider creating a custom Dockerfile with a non-root user for production.

2. **Volume Permissions:**
   Ensure mounted directories have appropriate permissions and don't expose sensitive data.

3. **Network Security:**
   If using HTTP transport, consider using reverse proxy with SSL/TLS and authentication if the endpoint is available on
   a network.

4. **IMPORTANT:** the https have no auhorization. They should not be exposed on a public network.  

## Integration Examples

### Claude Desktop with Docker

The recommended way to connect Claude Desktop to the containerized Basic Memory is using `mcp-proxy`, which converts the HTTP transport to STDIO that Claude Desktop expects:

1. **Start the Docker container:**
   ```bash
   docker-compose up -d
   ```

2. **Configure Claude Desktop** to use mcp-proxy:
   ```json
   {
     "mcpServers": {
       "basic-memory": {
         "command": "uvx",
         "args": [
           "mcp-proxy",
           "http://localhost:8000/mcp"
         ]
       }
     }
   }
   ```


## Support

For Docker-specific issues:

1. Check the [troubleshooting section](#troubleshooting) above
2. Review container logs: `docker-compose logs basic-memory`
3. Verify volume mounts: `docker inspect basic-memory-server`
4. Test file permissions: `docker exec basic-memory-server ls -la /root`

For general Basic Memory support, see the main [README](../README.md)
and [documentation](https://memory.basicmachines.co/).