Skip to content

deployment.md

Latest commit

 

History

History
94 lines (72 loc) · 2.28 KB

deployment.md

File metadata and controls

94 lines (72 loc) · 2.28 KB

Deployment Guide

Reverse Proxy with Caddy

Kagura Memory Cloud uses Caddy as a reverse proxy in production. Caddy provides automatic HTTPS, HTTP/2, and simple configuration.

Example Caddyfile

your-domain.example.com {
    # Health check for Caddy itself
    handle /caddy-health {
        respond "OK" 200
    }

    # Backend API
    reverse_proxy /api/* kagura-api:8080

    # Static files from backend
    reverse_proxy /static/* kagura-api:8080

    # MCP Streamable HTTP Transport
    reverse_proxy /mcp* kagura-api:8080 {
        flush_interval -1
        transport http {
            versions 1.1
        }
    }

    # OAuth2 and OpenAPI discovery endpoints
    handle /.well-known/* {
        reverse_proxy kagura-api:8080
    }

    # OpenAPI docs
    reverse_proxy /redoc kagura-api:8080
    reverse_proxy /openapi.json kagura-api:8080

    # Health check (proxied to API)
    reverse_proxy /health kagura-api:8080

    # Frontend (catch-all)
    reverse_proxy kagura-frontend:3000
}

Key Points

  • MCP endpoints (/mcp*) require flush_interval -1 for streaming support and HTTP/1.1 transport
  • .well-known endpoints are needed for OAuth2 discovery (RFC 8414)
  • The frontend acts as a catch-all for all other routes (Next.js App Router)
  • Caddy automatically provisions TLS certificates via Let's Encrypt

Docker Compose Integration

Add Caddy as a service in your docker-compose.yml:

services:
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - kagura-api
      - kagura-frontend

volumes:
  caddy_data:
  caddy_config:

Frontend Environment Variables

Copy frontend/.env.example to frontend/.env.local and configure:

# Required: Backend API URL (must be accessible from the browser)
NEXT_PUBLIC_API_URL=https://api.your-domain.com

# Required: Frontend URL (for OpenGraph metadata)
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Optional: Custom plan display names (default: S/M/L)
# NEXT_PUBLIC_PLAN_FREE_DISPLAY_NAME=Free
# NEXT_PUBLIC_PLAN_BASIC_DISPLAY_NAME=Standard
# NEXT_PUBLIC_PLAN_PRO_DISPLAY_NAME=Premium