Kiwix Helm Chart

Helm chart for deploying kiwix-serve with automated ZIM file downloads.

Features

• 🚀 Automated ZIM file downloads with retry logic and checksum verification
• 🔄 One-time or periodic download modes (Job or CronJob)
• 📦 OCI-based Helm chart distribution via GHCR
• 🛡️ Built on the bjw-s Common library
• 💾 Persistent storage with configurable size and storage class
• 🎯 Keep-all file management strategy for archival use cases
• 🔄 Automated dependency updates with Renovate

Prerequisites

• Kubernetes 1.19+
• Helm 3.8+
• Persistent Volume provisioner (for PVC support)

Installation

Install from OCI Registry

# Login to GHCR (if repository is private)
helm registry login ghcr.io -u <username>

# Install chart
helm install my-kiwix oci://ghcr.io/jacaudi/charts/kiwix \
  --version v0.1.0 \
  --namespace kiwix \
  --create-namespace \
  --values values.yaml

Install from Source

# Clone repository
git clone https://github.com/jacaudi/kiwix-helm-chart.git
cd kiwix-helm-chart

# Update dependencies
helm dependency update

# Install
helm install my-kiwix . \
  --namespace kiwix \
  --create-namespace \
  --values values.yaml

Configuration

See docs/VALUES.md for complete values documentation.

Quick Start Values

# Minimal configuration
persistence:
  size: 100Gi

ingress:
  enabled: true
  host: kiwix.local

For production deployments, see docs/VALUES.md for examples.

Architecture

The chart uses a standalone downloader pattern with two controllers:

1. Downloader Controller: Job (one-time) or CronJob (periodic) that downloads ZIM files to shared storage
2. Main Controller: Deployment running kiwix-serve that serves the downloaded files

Both controllers share a PVC mounted at /data. The downloader reads URLs from a ConfigMap generated from zimFiles.

User provides zimFiles list
        ↓
    ConfigMap (zim-urls.json)
        ↓
    Downloader (Job/CronJob)
        ↓
    PVC (/data)
        ↓
    Kiwix-serve (Deployment)

Storage Considerations

ZIM files can be large (100MB - 100GB). The chart uses a keep-all strategy, accumulating files over time.

Recommended PVC sizes:

• Small demo (1-2 files): 10-50 Gi
• Medium archive (5-10 files): 100-200 Gi
• Large archive (20+ files): 500+ Gi

Monitor PVC usage over time, especially when using periodic updates.

Automated Dependency Updates

This project uses Renovate to automatically keep dependencies up-to-date:

• GitHub Actions: Auto-updated to latest versions
• Docker base images: Tracks Alpine Linux releases
• Helm dependencies: Monitors bjw-s common library updates
• Container images: Tracks kiwix-serve and downloader versions

Schedule: Daily at 2am UTC

Auto-merge policy: Patch updates (1.0.x) automatically merge after 3 days if CI passes.

Dependency Dashboard: Check the Dependency Dashboard issue for pending updates.

Manual Renovate Run

Trigger Renovate manually via GitHub Actions:

gh workflow run renovate.yaml

Or via GitHub UI: Actions → Renovate → Run workflow

Release Workflow

This project uses Uplift to automate semantic versioning and releases.

Conventional Commits

All commits must follow Conventional Commits format:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: - New feature (minor version bump)
• fix: - Bug fix (patch version bump)
• docs: - Documentation changes
• chore: - Maintenance tasks
• refactor: - Code refactoring
• BREAKING CHANGE: in footer - Major version bump

Examples:

git commit -m "feat: add support for custom ZIM checksums"
git commit -m "fix: correct CronJob schedule parsing"
git commit -m "docs: update installation instructions"

Creating a Release

Releases are created manually via GitHub Actions:

1. Navigate to Actions → CI/CD Pipeline
2. Click Run workflow
3. Select main branch
4. Check Trigger Release option
5. Click Run workflow

Uplift will:

• Analyze commits since last release
• Determine version bump (major/minor/patch)
• Update Chart.yaml version and appVersion
• Generate/update CHANGELOG.md
• Create git tag (e.g., v0.2.0)
• Create GitHub release with changelog
• Trigger Docker and Helm chart publishing

Quality gates: Tests and builds must pass before release job runs.

Troubleshooting

Check Downloader Logs

# For Job
kubectl logs -n kiwix job/my-kiwix-downloader

# For CronJob (get latest job)
kubectl logs -n kiwix $(kubectl get jobs -n kiwix -l app.kubernetes.io/name=kiwix -o name | tail -1)

Verify Downloaded Files

kubectl exec -n kiwix deployment/my-kiwix -- ls -lh /data

Test Kiwix Service

# Port-forward
kubectl port-forward -n kiwix svc/my-kiwix 8080:8080

# Access in browser
open http://localhost:8080

Common Issues

Download timeout: Increase Job timeout or check network connectivity

downloader:
  resources:
    limits:
      cpu: 1000m
      memory: 512Mi

PVC full: Increase size or manually delete old files

kubectl exec -n kiwix deployment/my-kiwix -- rm /data/old-file.zim

Development

Building Downloader Image

cd image
docker build -t ghcr.io/jacaudi/kiwix-downloader:test .
docker push ghcr.io/jacaudi/kiwix-downloader:test

Testing Chart Locally

# Lint
helm lint .

# Template
helm template test . --values values.yaml

# Dry-run install
helm install test . --dry-run --debug

License

See repository license.

Contributing

Contributions welcome! Please open an issue or pull request.