eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/zk/kiwix.md
Erich Blume 7112297150 Move zk cards to docs/zk/ for documentation restructuring 
Phase 1 of docs restructuring: move all zettelkasten cards to a
temporary docs/zk/ subdirectory while preparing to build a new
Diataxis-based documentation structure.

- Move all existing markdown files from docs/ to docs/zk/
- Update zk-docs mise task to look in the new location
- Add docs/README.md explaining the restructuring plan

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 07:57:47 -08:00

3.4 KiB
Raw Blame History

id aliases tags
kiwix
kiwix
blumeops

Kiwix Management Log

Kiwix serves offline Wikipedia (and other ZIM archives) in Kubernetes via Tailscale at https://kiwix.tail8d86e.ts.net.

Service Details

  • URL: https://kiwix.tail8d86e.ts.net
  • Namespace: kiwix
  • Image: ghcr.io/kiwix/kiwix-serve:3.8.1
  • ArgoCD app: kiwix
  • Storage: NFS mount from sifaka (/volume1/torrents)

Architecture

The kiwix deployment has two components:

  1. kiwix-serve - Main container serving ZIM files at port 80
  2. torrent-sync - Sidecar that syncs declarative ZIM torrent list to Transmission

A CronJob (zim-watcher) runs hourly to detect new ZIM files and trigger a deployment restart when needed.

Useful Commands

# View kiwix logs
kubectl --context=minikube-indri -n kiwix logs -f deployment/kiwix -c kiwix-serve

# View torrent sync logs
kubectl --context=minikube-indri -n kiwix logs -f deployment/kiwix -c torrent-sync

# Check ZIM watcher job
kubectl --context=minikube-indri -n kiwix get cronjob zim-watcher

# Manually trigger ZIM watcher
kubectl --context=minikube-indri -n kiwix create job --from=cronjob/zim-watcher zim-watcher-manual

# Sync from ArgoCD
argocd app sync kiwix

ArgoCD Management

Kiwix is deployed via ArgoCD from argocd/manifests/kiwix/:

  • deployment.yaml - Kiwix-serve + torrent-sync sidecar
  • service.yaml - ClusterIP service
  • ingress-tailscale.yaml - Tailscale Ingress
  • configmap-zim-torrents.yaml - Declarative list of ZIM torrents to download
  • configmap-sync-script.yaml - Script to sync torrents to Transmission
  • cronjob-zim-watcher.yaml - Hourly job to restart kiwix on new ZIMs

Adding New ZIM Archives

  1. Edit argocd/manifests/kiwix/configmap-zim-torrents.yaml
  2. Add the torrent URL from https://download.kiwix.org/zim/
  3. Sync the kiwix app: argocd app sync kiwix
  4. The torrent-sync sidecar will add the torrent to transmission
  5. Once downloaded, the zim-watcher CronJob will detect it and restart kiwix

Configured Archives

The declarative torrent list includes:

  • Wikipedia top 1M English articles with images
  • Project Gutenberg (60,000+ public domain books)
  • iFixit repair guides
  • Stack Exchange sites (SuperUser, Math, etc.)
  • LibreTexts textbooks (Bio, Chem, Eng, Math, Phys, Humanities)
  • DevDocs (developer documentation bundles)

See argocd/manifests/kiwix/configmap-zim-torrents.yaml for the full list.

Storage

ZIM files are stored on sifaka NAS at /volume1/torrents/complete/. The kiwix pod mounts this directory via NFS.

Note: The NFS mount works because minikube uses the docker driver which NATs through indri's LAN IP, allowing direct access to sifaka.

Log

2026-01-21 (P6)

  • Migrated to Kubernetes (Phase 6 of k8s migration)
  • Direct NFS mount from sifaka (no PVC, shared with transmission)
  • Torrent-sync sidecar adds configured ZIMs to Transmission
  • ZIM-watcher CronJob restarts deployment when new files appear
  • Tailscale Ingress at kiwix.tail8d86e.ts.net
  • Retired ansible kiwix role from indri

2026-01-14

  • Added transmission integration for background torrent downloads
  • Enabled Gutenberg, iFixit, SuperUser, Math SE, and all LibreTexts archives

2026-01-13

  • Added kiwix role to ansible playbook
  • Operationalized ZIM archive downloads with configurable list
  • Initial setup with kiwix-tools binary on indri
  • Managed via LaunchAgent on port 5501