# yaml-language-server: $schema=https://schema.zeabur.app/template.json
apiVersion: zeabur.com/v1
kind: Template
metadata:
    name: RAG Service
spec:
    description: |
        Deploy your own RAG (Retrieval-Augmented Generation) service with admin dashboard.
        Hybrid search (semantic + BM25), API key management, query analytics, and knowledge learning API.
        Powered by PostgreSQL with pgvector and an OpenAI-compatible AI provider.
    variables:
        - key: PUBLIC_DOMAIN
          type: DOMAIN
          name: Domain
          description: Domain to bind the RAG service to
        - key: ZEABUR_AI_HUB_API_KEY
          type: AI_HUB_KEY
          name: Zeabur AI Hub API Key
          description: Your Zeabur AI Hub API key for answer generation
        - key: GEMINI_API_KEY
          type: STRING
          name: Gemini API Key
          description: Your Google Gemini API key for generating embeddings
    tags:
        - AI
        - RAG
        - Search
    readme: |
        # RAG Service

        A complete RAG service with admin dashboard for managing your knowledge base.

        **Source code**: [github.com/zeabur/rag-service](https://github.com/zeabur/rag-service)

        ## Getting Started

        ### Step 1: Create a Zeabur Project

        Go to [Zeabur Dashboard](https://zeabur.com/projects) and create a new project.

        ### Step 2: Deploy

        Add **RAG Service** from the Marketplace and provide a **Zeabur AI Hub API
        Key** for answer generation plus a **Gemini API Key** for embeddings. The
        template creates a private PostgreSQL 17 service with pgvector and injects
        its connection string into the RAG service automatically.

        Schema migrations run automatically on first startup — no manual setup needed.

        ## Features

        - **Hybrid search**: semantic (pgvector) + BM25 keyword with RRF fusion
        - **Streaming RAG answers** via configurable LLM model
        - **Admin dashboard**: chunk browser, query signals, reports, audit log
        - **API key management** with scopes and expiry
        - **Knowledge learning API**: add new chunks via `/api/learn`
        - **Feedback collection** on query results

        ## API Endpoints

        | Endpoint | Method | Auth | Description |
        |----------|--------|------|-------------|
        | `/api/query` | POST | API key | Search knowledge base + optional RAG answer |
        | `/api/learn` | POST | API key | Add new knowledge chunks |
        | `/api/report` | POST | API key | Report content issues |
        | `/api/feedback` | POST | API key | Submit result feedback |
        | `/api/admin/*` | GET/POST | API key (admin) | API key management, signals, reports, chunks |
        | `/dashboard` | GET | Basic Auth | Admin dashboard |

        ### Quick Test

        ```bash
        curl -X POST "https://your-domain/api/query" \
          -H "Authorization: Bearer $RAG_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"query": "how to deploy", "mode": "hybrid", "top_k": 5}'
        ```

        ## Agent Integration (Claude Code Plugin)

        Install the plugin to let Claude Code agents search and contribute to your knowledge base:

        ```bash
        claude plugins marketplace add zeabur/rag-service
        claude plugins install rag-service@rag-service
        claude
        # Inside Claude Code, run: /zeabur-rag-setup
        ```

        The plugin provides 8 skills: `search`, `learn`, `report` for everyday use, and `triage`, `inspect`, `edit`, `curate` for admin curation. Agents automatically search the KB when answering questions and can contribute new knowledge after solving problems.

        ## Environment Variables

        | Variable | Required | Description |
        |----------|----------|-------------|
        | `DATABASE_URL` | Auto | Private PostgreSQL connection string |
        | `ZEABUR_AI_HUB_API_KEY` | Yes | [Zeabur AI Hub](https://zeabur.com/ai-hub) key for LLM inference |
        | `GEMINI_API_KEY` | Yes | [Gemini API](https://ai.google.dev/gemini-api/docs/api-key) key for embeddings |
        | `EMBEDDING_MODEL` | No | Embedding model (default: `gemini-embedding-2`) |
        | `EMBEDDING_DIMENSIONS` | No | pgvector dimension (default: `1536`) |
        | `RAG_API_KEY` | Auto | API key for service access (auto-generated) |
        | `RAG_BASIC_AUTH` | Auto | Dashboard auth (auto-generated, format `admin:password`) |
        | `RAG_MODEL` | No | LLM model (default: `gemini-2.5-flash-lite`) |
        | `CORS_ORIGIN` | No | CORS origin (default: service URL) |

        Embeddings use **`gemini-embedding-2`** (1536d) through the Gemini API by default.

        Schema migrations run automatically on first startup.

        ## License

        [MIT](https://github.com/zeabur/rag-service) — Built by [Zeabur](https://zeabur.com)
    services:
        - name: postgresql
          icon: https://cdn.zeabur.com/marketplace/postgresql.svg
          template: PREBUILT
          spec:
            id: postgresql
            source:
                image: pgvector/pgvector:pg17
                command:
                    - docker-entrypoint.sh
                    - -c
                    - config_file=/etc/postgresql/postgresql.conf
            ports:
                - id: database
                  port: 5432
                  type: TCP
            volumes:
                - id: data
                  dir: /var/lib/postgresql/data
            env:
                PGDATA:
                    default: /var/lib/postgresql/data/pgdata
                POSTGRES_CONNECTION_STRING:
                    default: postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DATABASE}
                    expose: true
                POSTGRES_DATABASE:
                    default: ${POSTGRES_DB}
                    expose: true
                POSTGRES_DB:
                    default: rag
                POSTGRES_HOST:
                    default: ${CONTAINER_HOSTNAME}
                    expose: true
                POSTGRES_PASSWORD:
                    default: ${PASSWORD}
                    expose: true
                POSTGRES_PORT:
                    default: ${DATABASE_PORT}
                    expose: true
                POSTGRES_USER:
                    default: rag
                POSTGRES_USERNAME:
                    default: ${POSTGRES_USER}
                    expose: true
            configs:
                - path: /etc/postgresql/postgresql.conf
                  template: |
                    listen_addresses = '*'
                    max_connections = 100
                    shared_buffers = 128MB
                    dynamic_shared_memory_type = posix
                    max_wal_size = 1GB
                    min_wal_size = 80MB
                    log_timezone = 'UTC'
                    datestyle = 'iso, mdy'
                    timezone = 'UTC'
                    default_text_search_config = 'pg_catalog.simple'
                  permission: null
                  envsubst: null
        - name: rag-service
          dependencies:
            - postgresql
          template: PREBUILT_V2
          spec:
            id: rag-service
            source:
                image: zeabur/rag-service:latest
            ports:
                - id: web
                  port: 3000
                  type: HTTP
            instructions:
                - title: Username
                  content: admin
                - title: Password / RAG_API_KEY
                  content: ${PASSWORD}
            env:
                CORS_ORIGIN:
                    default: ${ZEABUR_WEB_URL}
                DATABASE_URL:
                    default: ${POSTGRES_CONNECTION_STRING}
                EMBEDDING_API_KEY:
                    default: ${GEMINI_API_KEY}
                EMBEDDING_API_URL:
                    default: https://generativelanguage.googleapis.com/v1beta/openai
                EMBEDDING_DIMENSIONS:
                    default: "1536"
                EMBEDDING_MODEL:
                    default: gemini-embedding-2
                RAG_API_KEY:
                    default: ${PASSWORD}
                RAG_BASIC_AUTH:
                    default: admin:${PASSWORD}
                RAG_MODEL:
                    default: gemini-2.5-flash-lite
                ZEABUR_AI_HUB_API_KEY:
                    default: ${ZEABUR_AI_HUB_API_KEY}
                ZEABUR_AI_HUB_URL:
                    default: https://hnd1.aihub.zeabur.ai/v1
          domainKey: PUBLIC_DOMAIN