Skip to Content
KnowledgeSDKDeployment

Deployment

Das KnowledgeSDK kann auf verschiedene Arten betrieben werden: als NPM-Paket in einer eigenen Anwendung, als Docker-Container oder lokal ueber die ProcessCube CLI (pc knowledge).

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 aus dem Marketplace beziehen.

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.

ProcessCube CLI (pc knowledge)

Fuer den lokalen Betrieb ohne Node.js oder Docker wird keine eigene KnowledgeSDK-Binary mehr gebaut. Das SDK ist in die ProcessCube CLI integriert und wird ueber pc knowledge bedient — das pc-Binary bringt SQLite ueber bun:sqlite mit, ein nativer better-sqlite3-Build ist damit nicht mehr noetig.

Installation

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

Details und Binaries pro Plattform: CLI-Installation.

Befehle

pc knowledge init
pc knowledge add-source filesystem ./docs
pc knowledge index

Im pc-Binary laeuft die Suche als FTS5 + bm25 mit optionalem LLM-Reranking (Voyage/Cohere). Der Vektor-Hybrid (sqlite-vec) ist Node-only — dafuer die Docker-Images oder das NPM-Paket verwenden.

Die vollstaendige Befehlsreferenz inklusive entfernter REST-/MCP-Quellen und Wiki-Layer steht unter Knowledge-Befehle.

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