Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers deploying KiwiFS to a Kubernetes cluster with persistent storage, configuration, and health checks.

​
Basic deployment

Create a Deployment and Service to run KiwiFS in your cluster.
kiwifs-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kiwifs
  labels:
    app: kiwifs
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kiwifs
  template:
    metadata:
      labels:
        app: kiwifs
    spec:
      containers:
        - name: kiwifs
          image: kiwifs:latest
          args: ["serve", "--root", "/data", "--port", "3333"]
          ports:
            - containerPort: 3333
              name: http
          volumeMounts:
            - name: knowledge
              mountPath: /data
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            initialDelaySeconds: 3
            periodSeconds: 5
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "1000m"
      volumes:
        - name: knowledge
          persistentVolumeClaim:
            claimName: kiwifs-data
kiwifs-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: kiwifs
spec:
  selector:
    app: kiwifs
  ports:
    - port: 3333
      targetPort: http
      protocol: TCP
      name: http
  type: ClusterIP

​
Persistent storage

Use a PersistentVolumeClaim to store your knowledge base across pod restarts and rescheduling.
kiwifs-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: kiwifs-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard
Use ReadWriteOnce access mode. KiwiFS manages its own concurrency and should not have multiple pods writing to the same volume simultaneously.

​
Configuration

​
ConfigMap

Store your KiwiFS configuration in a ConfigMap and mount it into the pod.
kiwifs-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: kiwifs-config
data:
  config.toml: |
    [search]
    engine = "sqlite"

    [versioning]
    strategy = "git"

    [async]
    enabled = true
    batch_window_ms = 200
    batch_max_size = 50
Add the ConfigMap volume to your Deployment. 
spec:
  template:
    spec:
      containers:
        - name: kiwifs
          volumeMounts:
            - name: knowledge
              mountPath: /data
            - name: config
              mountPath: /data/.kiwi
      volumes:
        - name: knowledge
          persistentVolumeClaim:
            claimName: kiwifs-data
        - name: config
          configMap:
            name: kiwifs-config

​
Secrets

Store sensitive values like API keys and connection strings in a Secret.
kiwifs-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: kiwifs-secrets
type: Opaque
stringData:
  api-key: "your-secret-api-key"
  openai-api-key: "sk-..."
  pgvector-dsn: "postgres://user:pass@pgvector:5432/kiwi?sslmode=disable"
Reference the Secret as environment variables in the Deployment. 
spec:
  template:
    spec:
      containers:
        - name: kiwifs
          args: ["serve", "--root", "/data", "--auth", "apikey"]
          env:
            - name: KIWIFS_API_KEY
              valueFrom:
                secretKeyRef:
                  name: kiwifs-secrets
                  key: api-key
            - name: OPENAI_API_KEY
              valueFrom:
                secretKeyRef:
                  name: kiwifs-secrets
                  key: openai-api-key
            - name: KIWI_PGVECTOR_DSN
              valueFrom:
                secretKeyRef:
                  name: kiwifs-secrets
                  key: pgvector-dsn

​
Health check probes

KiwiFS exposes three health endpoints.
EndpointPurposeUse as
/healthGeneral health statusInformational
/healthzLiveness checklivenessProbe
/readyzReadiness checkreadinessProbe
The liveness probe restarts the pod if KiwiFS becomes unresponsive. The readiness probe removes the pod from service endpoints until it finishes initializing and indexing. 
livenessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /readyz
    port: http
  initialDelaySeconds: 3
  periodSeconds: 5
  failureThreshold: 2

​
NFS export for native volume mounts

KiwiFS includes a userspace NFSv3 server. You can use it to expose your knowledge base as a native NFS volume to other pods in the cluster.
The NFS server runs entirely in userspace. It does not require privileged mode or host kernel NFS support.

​
Step 1: Enable NFS on the KiwiFS pod

Add the --nfs flag and expose port 2049. 
spec:
  template:
    spec:
      containers:
        - name: kiwifs
          args:
            - "serve"
            - "--root"
            - "/data"
            - "--nfs"
            - "--nfs-allow"
            - "10.0.0.0/8"
          ports:
            - containerPort: 3333
              name: http
            - containerPort: 2049
              name: nfs
Create a Service for the NFS port. 
apiVersion: v1
kind: Service
metadata:
  name: kiwifs-nfs
spec:
  selector:
    app: kiwifs
  ports:
    - port: 2049
      targetPort: nfs
      protocol: TCP
  type: ClusterIP

​
Step 2: Mount from other pods

Other pods can mount the NFS export as a standard NFS volume. 
spec:
  volumes:
    - name: knowledge
      nfs:
        server: kiwifs-nfs
        path: /
  containers:
    - name: app
      volumeMounts:
        - name: knowledge
          mountPath: /knowledge
          readOnly: true
Use readOnly: true on consumer pods to prevent accidental writes. Route all writes through the KiwiFS HTTP API instead.

​
Multi-space setup

Run multiple knowledge spaces by mounting separate PVCs and registering them with the --space flag. 
spec:
  template:
    spec:
      containers:
        - name: kiwifs
          args:
            - "serve"
            - "--root"
            - "/data/default"
            - "--space"
            - "team=/data/team"
            - "--space"
            - "docs=/data/docs"
          volumeMounts:
            - name: default-data
              mountPath: /data/default
            - name: team-data
              mountPath: /data/team
            - name: docs-data
              mountPath: /data/docs
      volumes:
        - name: default-data
          persistentVolumeClaim:
            claimName: kiwifs-default
        - name: team-data
          persistentVolumeClaim:
            claimName: kiwifs-team
        - name: docs-data
          persistentVolumeClaim:
            claimName: kiwifs-docs
Each space operates independently with its own directory, versioning history, and search index.

​
Ingress

Expose KiwiFS outside the cluster with an Ingress resource.
kiwifs-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kiwifs
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
  rules:
    - host: kiwi.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kiwifs
                port:
                  number: 3333
  tls:
    - hosts:
        - kiwi.example.com
      secretName: kiwifs-tls
Set proxy-body-size high enough to handle file uploads. The default nginx limit of 1MB is too low for most knowledge bases.
Last modified on May 4, 2026