Merge pull request #7 from basicmachines-co/docs/docker-guide

docs: add Docker deployment guide

Author: groksrc

src/config/navigation.ts

@@ -47,6 +47,7 @@ export const navConfig = {
         { title: 'Canvas', href: '/guides/canvas' },
         { title: 'CLI Reference', href: '/guides/cli-reference' },
         { title: 'AI Assistant Guide', href: '/guides/ai-assistant-guide' },
+        { title: 'Docker', href: '/guides/docker' },
       ],
     },
     {

src/pages/guides/docker.mdx

@@ -0,0 +1,251 @@
+---
+layout: '@/layouts/DocsLayout.astro'
+title: 'Docker'
+description: 'Run Basic Memory in Docker containers for server deployments and SSE transport'
+---
+
+import { Card, CardGroup, Info, Warning, Note, Tip, Steps, Step, CodeGroup, CodeTab } from '@/components'
+
+<Warning>
+The Docker image runs Basic Memory as an **SSE server** on port 8000. This is designed for server deployments where clients connect over HTTP, not for local MCP stdio connections with Claude Desktop.
+</Warning>
+
+## Overview
+
+Basic Memory provides official Docker images published to GitHub Container Registry. The container runs the MCP server with SSE (Server-Sent Events) transport, suitable for:
+
+- Server deployments where multiple clients connect remotely
+- Kubernetes or Docker Compose orchestration
+- CI/CD environments
+- Development and testing
+
+For local use with Claude Desktop or other MCP clients that use stdio transport, we recommend installing via [Homebrew](/getting-started#homebrew-recommended) or [pip](/getting-started#pip-installation).
+
+## Quick Start
+
+### Pull the Image
+
+```bash
+docker pull ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+### Run the Container
+
+```bash
+docker run -d \
+  --name basic-container \
+  -p 8000:8000 \
+  -v ~/basic-memory-data:/app/data \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+The server will be available at `http://localhost:8000/mcp`.
+
+<Note>
+The `-v` flag mounts a local directory for persistent storage. Without it, your data will be lost when the container stops.
+</Note>
+
+## Image Details
+
+### Registry
+
+Images are published to GitHub Container Registry (GHCR):
+
+```
+ghcr.io/basicmachines-co/basic-memory
+```
+
+### Available Tags
+
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest stable release |
+| `0.17.5` | Specific version |
+| `0.17` | Latest patch for minor version |
+
+### Architectures
+
+Multi-platform images are available for:
+- `linux/amd64` (Intel/AMD)
+- `linux/arm64` (Apple Silicon, ARM servers)
+
+Docker automatically pulls the correct architecture for your platform.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Path to Basic Memory data |
+| `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for projects |
+
+### Volume Mounts
+
+Mount a local directory to persist data:
+
+```bash
+docker run -d \
+  -v /path/to/local/data:/app/data \
+  -p 8000:8000 \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+### Port Configuration
+
+The container exposes port 8000 by default. Map to a different host port if needed:
+
+```bash
+docker run -d \
+  -p 3000:8000 \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+## Docker Compose
+
+For more complex setups, use Docker Compose:
+
+```yaml
+version: '3.8'
+
+services:
+  basic-container:
+    image: ghcr.io/basicmachines-co/basic-memory:latest
+    container_name: basic-container
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - BASIC_MEMORY_HOME=/app/data/basic-memory
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "basic-memory", "--version"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+Run with:
+
+```bash
+docker compose up -d
+```
+
+## Connecting to the Server
+
+### MCP SSE Configuration
+
+Configure your MCP client to connect via SSE transport:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "transport": {
+        "type": "sse",
+        "url": "http://localhost:8000/mcp"
+      }
+    }
+  }
+}
+```
+
+### Health Check
+
+Verify the server is running:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Or check container health:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' basic-container
+```
+
+## Running CLI Commands
+
+You can run Basic Memory CLI commands inside the container. Note that the first argument is the container name (`basic-container`) and the second is the CLI command (`basic-memory`):
+
+```bash
+# Check version
+docker exec basic-container basic-memory --version
+
+# Check status
+docker exec basic-container basic-memory status
+
+# List projects
+docker exec basic-container basic-memory project list
+```
+
+## Security
+
+The container runs as a non-root user (`appuser`) for security. Key security features:
+
+- Non-root execution (UID/GID 1000 by default)
+- No unnecessary packages installed
+- Health checks enabled
+- Slim base image (Python 3.12 slim-bookworm)
+
+### Custom UID/GID
+
+Build with custom user IDs for permission compatibility:
+
+```bash
+docker build --build-arg UID=1001 --build-arg GID=1001 -t basic-memory:custom .
+```
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+If you see permission errors with mounted volumes:
+
+```bash
+# Fix ownership on host
+sudo chown -R 1000:1000 /path/to/local/data
+
+# Or run with matching UID
+docker run --user $(id -u):$(id -g) ...
+```
+
+### Container Exits Immediately
+
+Check the logs:
+
+```bash
+docker logs basic-container
+```
+
+Common causes:
+- Port 8000 already in use
+- Volume mount path doesn't exist
+- Insufficient permissions
+
+### SSE vs Stdio Transport
+
+<Warning>
+The Docker image is configured for SSE transport only. It cannot be used as a stdio MCP server for Claude Desktop directly.
+</Warning>
+
+For Claude Desktop integration, either:
+1. Install Basic Memory locally via Homebrew or pip
+2. Use the SSE transport configuration (if your Claude Desktop version supports it)
+
+## Building from Source
+
+Clone the repository and build locally:
+
+```bash
+git clone https://github.com/basicmachines-co/basic-memory.git
+cd basic-memory
+docker build -t basic-memory:local .
+```
+
+## See Also
+
+- [Getting Started](/getting-started) - Local installation options
+- [CLI Reference](/guides/cli-reference) - Command line interface
+- [MCP Tools Reference](/guides/mcp-tools-reference) - Available MCP tools