Kiwix Serve

kiwix-serve is a lightweight HTTP daemon that exposes the contents of ZIM archives—self‑contained, compressed web collections—for offline consumption. From a developer’s standpoint it is essentially an HTTP server with a very narrow, well‑defined API surface: the ability to serve files from one or more ZIM archives and provide minimal search capabilities through a query string. The daemon is written in C++17, uses the libkiwix and libzim libraries for archive handling, and is built with the Meson build system. It ships as a statically linked binary by default, making it ideal for containerization or deployment on resource‑constrained devices such as Raspberry Pi or embedded routers.

• Core runtime – A single‑threaded event loop powered by libkiwix’s HTTP server module. The daemon parses incoming requests, maps URL paths to ZIM internal paths, and streams the corresponding data chunks.
• Archive layer – libzim provides random‑access to the compressed ZIM file, allowing efficient retrieval of HTML pages, images, and binary assets without decompressing the entire archive.
• Search integration – kiwix-search can be invoked as a child process or integrated via the optional /search?q= endpoint, returning JSON results that include URLs, titles, and snippets.
• Configuration – A simple INI‑style file (kiwix-serve.conf) allows binding to a specific IP/port, specifying the library XML (which lists multiple ZIMs), and toggling TLS support via OpenSSL. The daemon exposes a /status endpoint for health checks.

The stack is intentionally minimal: no external web frameworks, no database layer beyond the embedded SQLite used by libkiwix for library metadata. This reduces attack surface and simplifies dependency management.

• ZIM serving – Maps URLs such as /en/ or /fr/index.html directly to entries in the archive. The server honors MIME types, supports byte‑range requests for streaming media, and sets appropriate cache headers.
• Library management – By pointing the daemon to a library.xml, developers can host multiple ZIMs under a single process, exposing them as separate virtual hosts (/en/, /es/, etc.).
• Search API – Optional integration with kiwix-search provides a RESTful endpoint (/search?q=) that returns JSON, enabling developers to build custom search UIs or integrate with existing search frameworks.
• TLS support – When compiled with OpenSSL, the daemon can serve over HTTPS, essential for secure kiosk deployments.
• Metrics – Exposes basic Prometheus‑style metrics on /metrics, useful for monitoring traffic and cache hit ratios.

• Containerization – Official Docker images (ghcr.io/kiwix/kiwix-tools:latest) bundle the daemon with pre‑compiled libraries, making it trivial to spin up a container on Docker‑Compose or Kubernetes.
• Scalability – While the daemon is single‑threaded, it can be horizontally scaled by running multiple instances behind a load balancer. Each instance serves its own copy of the ZIM archive, which can be mounted via NFS or a distributed filesystem for consistency.
• Resource footprint – A typical deployment uses < 50 MB of RAM and a single CPU core, allowing it to run on low‑power devices or as part of an offline hotspot solution.
• Self‑hosting – No external services are required; all content is stored locally on disk, ensuring full control over data and compliance with privacy regulations.

• Plugin hooks – libkiwix exposes a C API that developers can wrap in custom modules (e.g., authentication, logging, or analytics).
• Webhooks – The /status and /metrics endpoints can be polled or pushed to external monitoring systems.
• Custom routing – By modifying the source, developers can add virtual hosts or rewrite rules, turning kiwix-serve into a generic static file server with ZIM support.
• API extensions – The search endpoint can be extended to accept additional filters (language, category) or to return richer metadata such as full article bodies.

• Documentation – The project hosts comprehensive ReadTheDocs coverage, including API references for libkiwix and libzim.
• Community – Active GitHub discussions, a mailing list, and a Discord channel provide quick support for integration questions.
• Configuration simplicity – A single INI file plus optional TLS certificates is all that’s needed to get a production‑ready server up and running.
• Licensing – GPLv3 ensures that any derivative work remains open source, which is advantageous for educational or research deployments.

1. Offline education kiosks – Deploy kiwix-serve on a Raspberry Pi to provide students in remote areas with access to Wikipedia, Khan Academy, and other ZIMs.
2. Library digital archives – Host institutional ZIM collections (e.g., local history, legal documents) behind a lightweight HTTP server.
3. Travel hotspots – Create an offline hotspot in tourist areas, serving travel guides