docs: add Docker deployment implementation plan

2025-12-29 19:37:59 -05:00
parent efe3ddf27b
commit 6782861cff
1 changed files with 444 additions and 0 deletions
--- a/docs/plans/2025-12-29-docker-deployment.md
+++ b/docs/plans/2025-12-29-docker-deployment.md
@@ -0,0 +1,444 @@
+# Docker Deployment Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make grist-mcp deployable via Docker Compose with automated CI builds on version tag pushes.
+
+**Architecture:** Replace stdio transport with SSE (HTTP-based) for remote operation. Multi-stage Dockerfile for small images. Single adaptive CI workflow that detects Gitea vs GitHub and pushes to the appropriate registry.
+
+**Tech Stack:** Python 3.14, Starlette (ASGI), Uvicorn, Docker, GitHub Actions (compatible with Gitea Actions)
+
+---
+
+### Task 1: Add SSE Transport Dependencies
+
+**Files:**
+- Modify: `pyproject.toml`
+
+**Step 1: Add dependencies to pyproject.toml**
+
+Edit `pyproject.toml` to add the SSE transport dependencies:
+
+```python
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0",
+    "starlette>=0.41.0",
+    "uvicorn>=0.32.0",
+    "sse-starlette>=2.1.0",
+]
+```
+
+**Step 2: Sync dependencies**
+
+Run: `uv sync`
+Expected: Dependencies install successfully
+
+**Step 3: Commit**
+
+```bash
+git add pyproject.toml uv.lock
+git commit -m "feat: add SSE transport dependencies"
+```
+
+---
+
+### Task 2: Implement SSE Transport in main.py
+
+**Files:**
+- Modify: `src/grist_mcp/main.py`
+
+**Step 1: Replace main.py with SSE implementation**
+
+Replace the entire contents of `src/grist_mcp/main.py` with:
+
+```python
+"""Main entry point for the MCP server with SSE transport."""
+
+import os
+import sys
+
+import uvicorn
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.routing import Route
+
+from grist_mcp.server import create_server
+from grist_mcp.auth import AuthError
+
+
+def create_app() -> Starlette:
+    """Create the Starlette ASGI application."""
+    config_path = os.environ.get("CONFIG_PATH", "/app/config.yaml")
+
+    if not os.path.exists(config_path):
+        print(f"Error: Config file not found at {config_path}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        server = create_server(config_path)
+    except AuthError as e:
+        print(f"Authentication error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    sse = SseServerTransport("/messages")
+
+    async def handle_sse(request):
+        async with sse.connect_sse(
+            request.scope, request.receive, request._send
+        ) as streams:
+            await server.run(
+                streams[0], streams[1], server.create_initialization_options()
+            )
+
+    async def handle_messages(request):
+        await sse.handle_post_message(request.scope, request.receive, request._send)
+
+    return Starlette(
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Route("/messages", endpoint=handle_messages, methods=["POST"]),
+        ]
+    )
+
+
+def main():
+    """Run the SSE server."""
+    port = int(os.environ.get("PORT", "3000"))
+    app = create_app()
+    print(f"Starting grist-mcp SSE server on port {port}")
+    print(f"  SSE endpoint: http://0.0.0.0:{port}/sse")
+    print(f"  Messages endpoint: http://0.0.0.0:{port}/messages")
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+**Step 2: Test that the server starts**
+
+Run: `CONFIG_PATH=./config.yaml.example GRIST_MCP_TOKEN=test uv run python -m grist_mcp.main &`
+Expected: Server starts, prints port info (will fail auth but that's OK for this test)
+Kill: `pkill -f "python -m grist_mcp.main"`
+
+**Step 3: Commit**
+
+```bash
+git add src/grist_mcp/main.py
+git commit -m "feat: replace stdio with SSE transport"
+```
+
+---
+
+### Task 3: Create Dockerfile
+
+**Files:**
+- Create: `Dockerfile`
+
+**Step 1: Create multi-stage Dockerfile**
+
+Create `Dockerfile` with:
+
+```dockerfile
+# Stage 1: Builder
+FROM python:3.14-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy dependency files
+COPY pyproject.toml uv.lock ./
+
+# Install dependencies
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy source code
+COPY src ./src
+
+# Install the project
+RUN uv sync --frozen --no-dev
+
+
+# Stage 2: Runtime
+FROM python:3.14-slim
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash appuser
+
+WORKDIR /app
+
+# Copy virtual environment from builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy source code
+COPY --from=builder /app/src ./src
+
+# Set environment
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PORT=3000
+
+# Switch to non-root user
+USER appuser
+
+EXPOSE 3000
+
+CMD ["python", "-m", "grist_mcp.main"]
+```
+
+**Step 2: Verify Dockerfile syntax**
+
+Run: `docker build --check .` (if available) or just proceed to next step
+
+**Step 3: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "feat: add multi-stage Dockerfile"
+```
+
+---
+
+### Task 4: Create docker-compose.yaml
+
+**Files:**
+- Create: `docker-compose.yaml`
+
+**Step 1: Create docker-compose.yaml**
+
+Create `docker-compose.yaml` with:
+
+```yaml
+services:
+  grist-mcp:
+    build: .
+    ports:
+      - "${PORT:-3000}:3000"
+    volumes:
+      - ./config.yaml:/app/config.yaml:ro
+    env_file:
+      - .env
+    restart: unless-stopped
+```
+
+**Step 2: Commit**
+
+```bash
+git add docker-compose.yaml
+git commit -m "feat: add docker-compose.yaml"
+```
+
+---
+
+### Task 5: Create .env.example
+
+**Files:**
+- Create: `.env.example`
+
+**Step 1: Create .env.example**
+
+Create `.env.example` with:
+
+```bash
+# grist-mcp environment configuration
+
+# Server port (default: 3000)
+PORT=3000
+
+# Agent authentication token (required)
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+GRIST_MCP_TOKEN=your-agent-token-here
+
+# Grist API keys (referenced in config.yaml)
+GRIST_WORK_API_KEY=your-work-api-key
+GRIST_PERSONAL_API_KEY=your-personal-api-key
+
+# Optional: Override config path (default: /app/config.yaml)
+# CONFIG_PATH=/app/config.yaml
+```
+
+**Step 2: Commit**
+
+```bash
+git add .env.example
+git commit -m "feat: add .env.example template"
+```
+
+---
+
+### Task 6: Create CI Workflow
+
+**Files:**
+- Create: `.github/workflows/build.yaml`
+
+**Step 1: Create workflow directory**
+
+Run: `mkdir -p .github/workflows`
+
+**Step 2: Create adaptive CI workflow**
+
+Create `.github/workflows/build.yaml` with:
+
+```yaml
+name: Build and Push Docker Image
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+env:
+  IMAGE_NAME: grist-mcp
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Determine registry
+        id: registry
+        run: |
+          if [ "${{ vars.GITEA_ACTIONS }}" = "true" ]; then
+            # Gitea: use server URL as registry
+            REGISTRY="${{ github.server_url }}"
+            REGISTRY="${REGISTRY#https://}"
+            REGISTRY="${REGISTRY#http://}"
+            echo "registry=${REGISTRY}" >> $GITHUB_OUTPUT
+            echo "is_gitea=true" >> $GITHUB_OUTPUT
+          else
+            # GitHub: use GHCR
+            echo "registry=ghcr.io" >> $GITHUB_OUTPUT
+            echo "is_gitea=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Log in to GitHub Container Registry
+        if: steps.registry.outputs.is_gitea == 'false'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log in to Gitea Container Registry
+        if: steps.registry.outputs.is_gitea == 'true'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ steps.registry.outputs.registry }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ steps.registry.outputs.registry }}/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/build.yaml
+git commit -m "feat: add CI workflow for Docker builds"
+```
+
+---
+
+### Task 7: Update README with Docker Instructions
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Read current README**
+
+Read `README.md` to understand current structure.
+
+**Step 2: Add Docker section after existing content**
+
+Add a "Docker Deployment" section with:
+- Quick start with docker-compose
+- Environment variable reference
+- Configuration instructions
+
+**Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add Docker deployment instructions"
+```
+
+---
+
+### Task 8: Test Docker Build Locally
+
+**Files:**
+- None (verification only)
+
+**Step 1: Build the Docker image**
+
+Run: `docker build -t grist-mcp:test .`
+Expected: Build completes successfully
+
+**Step 2: Create test config and .env**
+
+Run:
+```bash
+cp config.yaml.example config.yaml
+cp .env.example .env
+```
+
+Edit `.env` to set a test token matching one in `config.yaml`.
+
+**Step 3: Test with docker-compose**
+
+Run: `docker compose up -d`
+Expected: Container starts
+
+**Step 4: Verify server is running**
+
+Run: `curl -I http://localhost:3000/sse`
+Expected: HTTP response (connection may hang waiting for SSE, that's OK)
+
+**Step 5: Clean up**
+
+Run: `docker compose down`
+
+**Step 6: Final commit if any fixes needed**
+
+If any fixes were required, commit them.
+
+---
+
+## Post-Implementation
+
+After all tasks complete:
+
+1. **Tag a version:** `git tag v0.2.0 && git push --tags`
+2. **Configure Gitea secret:** Add `REGISTRY_TOKEN` in Gitea repo settings
+3. **Verify CI:** Check that workflow runs and pushes images