Skip to Content
KnowledgeSDKDeployment

Deployment

Das KnowledgeSDK kann auf verschiedene Arten betrieben werden: als NPM-Paket in einer eigenen Anwendung, als Docker-Container oder als Single-Binary.

Als NPM-Paket

Die einfachste Integration: Das SDK wird als Abhaengigkeit in eine bestehende Node.js-Anwendung eingebunden.

Installation

npm install @processcube-io/knowledge-sdk

Index erstellen

import { createIndexer, filesystemSource, githubSource } from '@processcube-io/knowledge-sdk';
 
const indexer = createIndexer({
  dbPath: './data/index.sqlite',
  collections: [
    {
      name: 'docs',
      path: './content',
      pattern: '**/*.md',
      context: 'Projekt-Dokumentation',
      group: 'Allgemein',
    },
  ],
  plugins: [filesystemSource, githubSource],
});
 
await indexer.run();

Server starten

import { createSearchStore } from '@processcube-io/knowledge-sdk';
import { startServer } from '@processcube-io/knowledge-sdk/adapters/standalone';
 
const store = await createSearchStore({ dbPath: './data/index.sqlite' });
await startServer(store, { port: 3001 });
 
// GET /api/search?q=...    — Suche
// GET /api/collections     — Collections auflisten
// GET /health              — Health-Check

Weitere Details: Getting Started | Framework-Adapter (Next.js, Express, Hono)

Docker-Images

Zwei Docker-Images fuer den Standalone-Betrieb ohne eigene Anwendung.

Voraussetzungen

Fuer den Zugriff auf die Docker-Images ist ein Login am ProcessCube Marketplace erforderlich:

echo "IHR_API_KEY" | docker login marketplace.processcube.io -u processcube --password-stdin

Den API-Key finden Sie in Ihrer ProcessCube-Rechnung. Details siehe Docker-Images verwenden.

Such-Server

docker run -d \
  -v qmd-data:/data \
  -p 3001:3001 \
  -e QMD_API_KEY=mein-geheimer-key \
  marketplace.processcube.io/processcube-io/knowledge-sdk-server

Umgebungsvariablen (Server)

VariableDefaultBeschreibung
QMD_INDEX_PATH/data/index.sqlitePfad zur Datenbank
QMD_SEARCH_MODEftsfts oder hybrid
QMD_EMBED_PROVIDERnonenone, openai, voyage
QMD_API_KEY(leer)API-Key fuer Auth (leer = kein Auth)
QMD_MCP_ENABLEDfalseMCP-Endpoint aktivieren
PORT3001Server-Port

Indexer

Der Indexer erstellt und aktualisiert den Such-Index. Die Konfiguration erfolgt ueber eine JSON-Datei.

docker run --rm \
  -v ./config.json:/app/config.json \
  -v qmd-data:/data \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  marketplace.processcube.io/processcube-io/knowledge-sdk-indexer

config.json

{
  "collections": [
    {
      "name": "docs",
      "path": "/content/docs",
      "pattern": "**/*.md",
      "context": "Projekt-Dokumentation",
      "group": "Allgemein"
    }
  ],
  "contentSources": [
    {
      "plugin": "github",
      "config": {
        "collection": "changelogs",
        "files": [
          {
            "owner": "org",
            "repo": "repo",
            "branch": "main",
            "path": "CHANGELOG.md",
            "outputName": "repo.md"
          }
        ]
      }
    }
  ]
}

Umgebungsvariablen (Indexer)

VariableDefaultBeschreibung
QMD_CONFIG/app/config.jsonPfad zur Config
QMD_INDEX_PATH/data/index.sqlitePfad zur Datenbank
QMD_EMBED_PROVIDERnoneEmbedding-Provider
SKIP_EMBEDfalseEmbeddings ueberspringen
GITHUB_TOKEN(leer)Fuer GitHub-Plugin

Env-Var-Syntax in der Config (${GITHUB_TOKEN}) wird beim Laden aufgeloest.

Single-Binary / CLI

Known Issue — Die Single-Binary wird zwar gebaut und veroeffentlicht, startet aber aktuell nicht aufgrund einer Inkompatibilitaet zwischen Bun und better-sqlite3 (nativer Node.js C++ Addon, ABI Mismatch). Siehe oven-sh/bun#16050 . Nutze stattdessen die Docker-Images oder das NPM-Paket.

knowledge-sdk kann als Single-Binary ohne Node.js oder Docker betrieben werden (kompiliert mit Bun).

Installation

curl -fsSL https://marketplace.processcube.io/knowledge-sdk/install | bash

Oder manuell von GitHub Releases .

Unterstuetzte Plattformen

PlattformBinaryExtension
macOS arm64 (Apple Silicon)knowledge-sdk-darwin-arm64vec0.dylib
Linux x64knowledge-sdk-linux-x64vec0.so
Windows x64knowledge-sdk-windows-x64vec0.dll

Befehle

knowledge-sdk index --config ./config.json

Vollstaendige Optionen

knowledge-sdk — Hybrid-Suche (BM25 + Vektor) als Single-Binary

Befehle:
  index   --config <file> [--output <db>]   Index erstellen/aktualisieren
  serve   --db <file> [--port 3001] [--mcp] Such-Server starten
  search  --db <file> -q <query> [--json]   Einmalige Suche

Umgebungsvariablen:
  QMD_INDEX_PATH      Pfad zur SQLite-Datenbank
  QMD_EMBED_PROVIDER  none | openai | voyage
  QMD_SEARCH_MODE     fts | hybrid
  QMD_API_KEY         API-Key fuer Auth (Serve-Modus)
  GITHUB_TOKEN        Fuer GitHub-Plugin (Index-Modus)

Dateistruktur

Nach der Installation:

~/.knowledge-sdk/
  knowledge-sdk              # Binary
  extensions/
    vec0.dylib            # SQLite-Extension (oder vec0.so auf Linux)
  plugins/
    confluence-source.ts   # Eigene Content-Source Plugins (optional)
    odoo-auth.ts           # Eigene Auth Plugins (optional)

Die Bun-Runtime in der Binary kann TypeScript direkt ausfuehren — kein Build-Schritt noetig.

Update / Deinstallation

# Update
curl -fsSL https://marketplace.processcube.io/knowledge-sdk/install | bash
 
# Spezifische Version
QMD_VERSION=knowledge-sdk-v0.2.0 curl -fsSL https://marketplace.processcube.io/knowledge-sdk/install | bash
 
# Deinstallation
rm -rf ~/.knowledge-sdk /usr/local/bin/knowledge-sdk

Kubernetes

Fuer den produktiven Betrieb in Kubernetes werden der Indexer als CronJob und der Server als Deployment betrieben. Beide teilen sich ein PersistentVolumeClaim fuer die SQLite-Datenbank.

CronJob (Indexer)

Der Indexer laeuft regelmaessig als CronJob und aktualisiert den Such-Index:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: qmd-indexer
spec:
  schedule: "*/30 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: indexer
              image: marketplace.processcube.io/processcube-io/knowledge-sdk-indexer
              env:
                - name: GITHUB_TOKEN
                  valueFrom:
                    secretKeyRef:
                      name: github-token
                      key: token
              volumeMounts:
                - name: index
                  mountPath: /data
                - name: config
                  mountPath: /app/config.json
                  subPath: config.json
          volumes:
            - name: index
              persistentVolumeClaim:
                claimName: qmd-index
            - name: config
              configMap:
                name: qmd-config
          restartPolicy: OnFailure

Deployment (Server)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: knowledge-sdk
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: server
          image: marketplace.processcube.io/processcube-io/knowledge-sdk-server
          ports:
            - containerPort: 3001
          env:
            - name: QMD_API_KEY
              valueFrom:
                secretKeyRef:
                  name: qmd-secret
                  key: api-key
          volumeMounts:
            - name: index
              mountPath: /data
              readOnly: true
          livenessProbe:
            httpGet:
              path: /health
              port: 3001
          readinessProbe:
            httpGet:
              path: /health
              port: 3001
      volumes:
        - name: index
          persistentVolumeClaim:
            claimName: qmd-index

PersistentVolumeClaim

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: qmd-index
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Da SQLite keine gleichzeitigen Schreibzugriffe unterstuetzt, muss das PVC im ReadWriteOnce-Modus betrieben werden. Der Server mountet das Volume als readOnly, sodass Indexer und Server auf demselben Node laufen koennen. Bei Bedarf kann eine podAffinity sicherstellen, dass der CronJob auf demselben Node wie das Deployment laeuft.

Eigene PluginsKonfiguration