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.

KiwiFS ships with a multi-stage Dockerfile and a docker-compose.yml that includes an optional pgvector sidecar for vector search.

​
Quick start

Pull and run the pre-built image from Docker Hub.
docker run -p 3333:3333 -v ./knowledge:/data ameliaanhlam/kiwifs
Your knowledge base is now available at http://localhost:3333.

​
Dockerfile

The Dockerfile uses a three-stage build to produce a minimal runtime image.
StageBase imagePurpose
1. Node.jsnode:22-alpineBuilds the React UI
2. Gogolang:1.25.5-alpineCompiles the Go binary with the UI embedded via go:embed
3. Runtimealpine:3.20Minimal image with git and ca-certificates
The final image contains only the compiled binary, git (for versioning), and root CA certificates.

​
Docker Compose

The included docker-compose.yml runs KiwiFS alongside an optional pgvector database for vector search.
docker-compose.yml
services:
  kiwifs:
    build: .
    ports:
      - "3333:3333"
      # Uncomment to expose additional protocols:
      # - "2049:2049"   # NFS
      # - "3334:3334"   # S3
      # - "3335:3335"   # WebDAV
    volumes:
      - ./knowledge:/data
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - KIWI_PGVECTOR_DSN=postgres://kiwi:kiwi@db:5432/kiwi?sslmode=disable
    depends_on:
      db:
        condition: service_healthy

  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: kiwi
      POSTGRES_PASSWORD: kiwi
      POSTGRES_DB: kiwi
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kiwi"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:
Start everything with a single command. 
docker compose up -d

​
Configuration

​
Environment variables

Pass environment variables to configure KiwiFS and enable integrations. 
docker run \
  -v ./knowledge:/data \
  -p 3333:3333 \
  -e OPENAI_API_KEY=sk-... \
  -e KIWI_PGVECTOR_DSN=postgres://user:pass@host:5432/db \
  kiwifs
In docker-compose.yml, add variables under the environment key or use an .env file. 
services:
  kiwifs:
    env_file: .env

​
Enable authentication

Pass auth flags as command arguments. 
docker run -v ./knowledge:/data -p 3333:3333 \
  kiwifs serve --auth apikey --api-key my-secret-key

​
Enable NFS, S3, and WebDAV

Uncomment the relevant port mappings in docker-compose.yml and add the corresponding flags. 
services:
  kiwifs:
    build: .
    ports:
      - "3333:3333"
      - "2049:2049"   # NFS
      - "3334:3334"   # S3
      - "3335:3335"   # WebDAV
    volumes:
      - ./knowledge:/data
    command: ["serve", "--nfs", "--s3", "--webdav"]
The NFS server runs in userspace (NFSv3) and does not require the container to run in privileged mode.

​
Volumes and persistence

The knowledge directory must be mounted as a volume so data persists across container restarts. 
volumes:
  - ./knowledge:/data      # Knowledge files
  - pgdata:/var/lib/postgresql/data  # Vector search database
If you omit the volume mount, all knowledge data is lost when the container stops.

​
Health checks

KiwiFS exposes health endpoints you can use in your Docker configuration. 
services:
  kiwifs:
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3333/healthz"]
      interval: 10s
      timeout: 3s
      retries: 3
EndpointPurpose
/healthBasic health check
/healthzLiveness probe
/readyzReadiness probe

​
Production tips

Pin the image tag in production. Build with a version tag (docker build -t kiwifs:1.2.0 .) and reference it explicitly in your compose file.
  • Set --async-commit=true (the default) for better write throughput under load.
  • Use --search sqlite for fast full-text search without external dependencies.
  • Mount the pgvector volume to a persistent disk if you use vector search.
  • Set resource limits in your compose file to prevent runaway memory usage.
services:
  kiwifs:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
Last modified on May 4, 2026