Docker

The published image runs the full server: REST API, web UI, MCP over HTTP, and the optional NFS, S3, and WebDAV protocols. It also bundles the tools for server-side document export.

Quick start

Published image
Build from source

Terminal

docker run -d --name kiwifs \
  -p 3333:3333 \
  -v ./knowledge:/data \
  ameliaanhlam/kiwifs

Images are published to Docker Hub as ameliaanhlam/kiwifs for linux/amd64 and linux/arm64. Each release is tagged with its version, such as 0.19.78, and latest follows the newest release.

Terminal

git clone https://github.com/kiwifs/kiwifs.git && cd kiwifs
docker build -t kiwifs .
docker run -d -p 3333:3333 -v ./knowledge:/data kiwifs

Open http://localhost:3333. If /data is empty, KiwiFS initializes a new knowledge base there on first start.

What’s in the image

The default command is:

kiwifs serve --root /data --port 3333 --host 0.0.0.0 --search sqlite

The entrypoint is kiwifs, so any arguments you pass replace that command. Always include --root /data when you pass your own.

Build stages and bundled tools

Stage	Base image	Purpose
UI	`node:22-alpine`	Builds the web UI
Builder	`golang:1.27-alpine`	Compiles a static binary with the UI embedded
Runtime	`alpine:3.20`	Runs KiwiFS as the non-root user `kiwi`

The runtime image includes git for versioning, Pandoc, Marp CLI, Chromium, and MkDocs for document export, and the Docker CLI. It doesn’t include Typst or XeLaTeX, so server-side PDF export needs a derived image.

Docker Compose

The repository’s docker-compose.yml builds the image and starts an optional pgvector database for vector search.

docker-compose.yml

services:
  kiwifs:
    build:
      context: .
    image: kiwifs
    ports:
      - "3333:3333"  # REST API + embedded UI
      # - "2049:2049"  # NFS    (requires --nfs)
      # - "3334:3334"  # S3     (requires --s3)
      # - "3335:3335"  # WebDAV (requires --webdav)
    volumes:
      - ./knowledge:/data
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
      KIWI_PGVECTOR_DSN: postgresql://kiwi:kiwi@db:5432/kiwi
    command:
      - serve
      - --root=/data
      - --port=3333
      - --host=0.0.0.0
      - --search=sqlite
      - --versioning=git
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

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

volumes:
  pgdata:

Terminal

docker compose up -d

To use the published image instead of building, replace build and image with image: ameliaanhlam/kiwifs:latest. For development, docker-compose.dev.yml runs the backend with hot reload on port 3333, the Vite dev server on port 5173, an MCP server on port 8181, and pgvector.

Configuration

Most settings live in .kiwi/config.toml inside the mounted knowledge root. See Optional features for the available sections.

Environment variables

KiwiFS reads these environment variables directly:

Variable	Overrides
`KIWI_BACKUP_REMOTE`	`[backup] remote`
`KIWI_BACKUP_INTERVAL`	`[backup] interval`
`KIWI_BACKUP_REBASE_BEFORE_PUSH`	`[backup] rebase_before_push`
`KIWI_PUBLIC_URL`	`[server] public_url`

Any other variable takes effect only when config.toml references it with ${VAR}. For example, the Compose file’s OPENAI_API_KEY and KIWI_PGVECTOR_DSN turn on vector search with this config:

.kiwi/config.toml

[search.vector]
enabled = true

[search.vector.embedder]
provider = "openai"
model = "text-embedding-3-small"
api_key = "${OPENAI_API_KEY}"

[search.vector.store]
provider = "pgvector"
dsn = "${KIWI_PGVECTOR_DSN}"

Restart the container. When the vector store is empty, KiwiFS embeds existing pages in the background on startup.

Authentication

Pass auth flags along with the rest of the serve command.

docker run -d -p 3333:3333 -v ./knowledge:/data \
  ameliaanhlam/kiwifs \
  serve --root /data --auth apikey --api-key "$KIWI_API_KEY"

docker run -d -p 3333:3333 -v ./knowledge:/data \
  ameliaanhlam/kiwifs \
  serve --root /data --auth oidc \
    --oidc-issuer https://accounts.google.com \
    --oidc-client-id my-client-id

To keep the key out of the process list, set [auth] api_key = "${KIWI_API_KEY}" in config.toml and pass -e KIWI_API_KEY instead. See Auth and tokens.

NFS, S3, and WebDAV

Publish the ports and enable each protocol.

docker-compose.yml

services:
  kiwifs:
    image: ameliaanhlam/kiwifs:latest
    ports:
      - "3333:3333"
      - "2049:2049"   # NFS
      - "3334:3334"   # S3
      - "3335:3335"   # WebDAV
    volumes:
      - ./knowledge:/data
    command: ["serve", "--root", "/data", "--nfs", "--nfs-allow", "172.16.0.0/12", "--s3", "--webdav"]

The NFS server runs in userspace (NFSv3), so the container doesn’t need privileged mode. It only accepts localhost by default, so set --nfs-allow to the CIDRs of your clients. See Alternate protocols.

Persistence and permissions

Mount the knowledge root at /data, or all pages and history are lost when the container is removed. Indexes in .kiwi/state/ are rebuildable, but your markdown files and .git are not. The server runs as the non-root user kiwi. If KiwiFS can’t write to a bind-mounted folder, make the folder writable for that user or run the container with --user "$(id -u):$(id -g)".

Health checks

Endpoint	Returns
`/health`	`{"status": "ok"}`
`/healthz`	Status, uptime, and version. Use it for liveness.
`/readyz`	`200` when storage is reachable and every enabled protocol listener is up, otherwise `503`. Use it for readiness.

These endpoints never require authentication. The image includes BusyBox wget, but not curl.

docker-compose.yml

services:
  kiwifs:
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3333/readyz"]
      interval: 10s
      timeout: 3s
      retries: 3

Production tips

Pin a version tag, such as ameliaanhlam/kiwifs:0.19.78, rather than latest.
Run one container per knowledge root. KiwiFS serializes writes inside one process.
Turn on backup sync to push history to a git remote.
Set memory limits, and raise them if you enable vector search.

docker-compose.yml

services:
  kiwifs:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"

Kubernetes

Run KiwiFS in a cluster.

Ollama vector search

Local embeddings on a small VPS.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Quick start

What’s in the image

Docker Compose

Configuration

Environment variables

Authentication

NFS, S3, and WebDAV

Persistence and permissions

Health checks

Production tips

Kubernetes

Ollama vector search

​Quick start

​What’s in the image

​Docker Compose

​Configuration

​Environment variables

​Authentication

​NFS, S3, and WebDAV

​Persistence and permissions

​Health checks

​Production tips

​Related

Kubernetes

Ollama vector search

Quick start

What’s in the image

Docker Compose

Configuration

Environment variables

Authentication

NFS, S3, and WebDAV

Persistence and permissions

Health checks

Production tips

Related