In this article we'll be deployingKiwix using docker and docker compose. You can look at thegithub repositories and contribute to its many projects (server, mobile, browser and desktop apps).

Here is an example of what it looks like:

Disclaimer

ℹ️ This article is helpful if you want to self-host anOFFLINE version of different sites (Wikipedia, Wikitionnary, Stack Exchange, DevDocs ...) in your home, or on a portable server to bring it with you (It should work on a Raspberry-Pi).

⚠️ This article isnot for you if you want to host and edit your own version of Wikipedia, but there should be resources onMediaWiki out there. You also don't need this if you just want to read.zim files directly on your local computer or phone, kiwix client apps are largely enough.

Setup Instructions

This installation was tested onubuntu 24.04, both server and desktop, but it should work on any system with docker installed. Most of this tutorial is a step-by-step guide largely inspired byjoinboiser github repository

Pre-requisites

• A system withdocker installed
• Your favorite command line
• Your favorite editor

Create the project structure and empty files:

mkdir-p kiwix/zimsmkdir-p kiwix/scriptscdkiwixtouchDockerfiletouchdocker-compose.ymltouchscripts/provision.shtouchscripts/entrypoint.shchmod +x scripts/provision.shchmod +x scripts/entrypoint.sh

Get static sites data

Kiwix uses.zim files, you can find a nice repository on theofficial kiwix downloads repository.

💡 To begin I would advise using tiny zim files to try out your setup, a full english wikipedia with images can take around 100GB and takes a while to download

For this example, we'll be downloading the following (From thekiwix folder:

wget https://download.kiwix.org/zim/devdocs/devdocs_en_ansible_2025-01.zim-O zims/devdocs-ansible-en_2025-01.zimwget https://download.kiwix.org/zim/devdocs/devdocs_en_typescript_2025-01.zim-O zims/devdocs-typescript-en_2025-01.zim

If you still want to download wikipedia, I am currently using this version (🚨 Very long to download):

wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi_2024-01.zim-O wikipedia-en_2024-01.zim

Setting up scripts

Add the following content to the empty scripts:

provision.sh

#!/bin/bashTGTDIR="${1:-/usr/local/bin}"VERSION="${VERSION:-3.1.2-4}"MACHINE="${MACHINE:-$(uname-m)}"URL="${URL:-"https://download.kiwix.org/release/kiwix-tools/kiwix-tools_linux-${MACHINE}-${VERSION}.tar.gz"}"DLPATH=${DLPATH:-/tmp}FILE="$DLPATH/${URL##*/}"# Install kiwix-tools from binary tarballset-x-ewget-O"$FILE""$URL"tar-xvf"$FILE"-C"$TGTDIR"--strip-components 1rm-f"$FILE"

entrypoint.sh

#!/bin/bashZIMDIR=${ZIMDIR:-/zims}LIBRARY_XML=/library.xmlforfin"$ZIMDIR"/*.zim;do  if[[-f"$f"]];then(set-x; kiwix-manage"$LIBRARY_XML" add$f)fidonekiwix-serve--port 8080--library"$LIBRARY_XML"

Setting up Dockerfile

Add this to your empty dockerfile:

FROM ubuntu:24.04ENV TGTDIR=/usr/local/binRUNenvLANG=CLC_ALL=C apt updateRUNenvDEBIAN_FRONTEND=noninteractiveLANG=CLC_ALL=C apt-get-y full-upgradeRUNenvDEBIAN_FRONTEND=noninteractiveLANG=CLC_ALL=C apt-get-y-o Dpkg::Options::="--force-confdef"-o Dpkg::Options::="--force-confold"installwgetVOLUME /zimsCOPY ./scripts/*.sh $TGTDIR/RUNprovision.shEXPOSE 8080ENTRYPOINT ["entrypoint.sh"]

💡 For testing purposes, you can comment the following line as it can take a while to execute:RUN env DEBIAN_FRONTEND=noninteractive LANG=C LC_ALL=C apt-get -y full-upgrade

Setting up the docker-compose file

Add this to your empty docker-compose:

services:kiwix:build:.container_name:kiwixports:-'8080:8080'volumes:-./zims:/zims:ronetworks:-kiwix_netnetworks:kiwix_net:driver:bridge

Yourkiwix folder should now look like this:

kiwix├── docker-compose.yml├── Dockerfile├── scripts│  ├── entrypoint.sh│  └── provision.sh└── zims   ├── devdocs-ansible-en_2025-01.zim   └── devdocs-typescript-en_2025-01.zim

Launching and testing

To launch our kiwix server, just execute:

docker compose up--build

The service should now be available at<server-hostname-or-ip>:8080. Uselocalhost:8080 if you deployed locally.

If you only addeddevdocs mentioned above, you should see something like this:

To stop the service:

docker compose stop

If you add newzim files, you just need torestart the service, adocker compose restart should suffice

[OPTIONAL] Using a systemd service

This will help you if you want to enable the service on boot and administer it throughsystemd.

First, create the log folders and unit file with:

sudo mkdir-p /var/log/kiwixtouchkiwix.service

Add and adapt the following to yourkiwix.service file:

[Unit]Description=KiwixAfter=network.targetStartLimitIntervalSec=0[Service]Type=simpleRestart=alwaysRestartSec=1User=<YOUR USER>ExecStart=/usr/bin/docker compose -f <path-to-kiwix-service>/docker-compose.yml up --buildExecStop=/usr/bin/docker compose -f <path-to-kiwix-service>/docker-compose.yml stopStandardOutput=append:/var/log/kiwix/kiwix.logStandardError=append:/var/log/kiwix/kiwix-err.log[Install]WantedBy=multi-user.target

Copy it to systemd configs:

sudo cp kiwix.service /etc/systemd/system

And then start and enable the systemd service:

# Reload configurationssudo systemctl daemon-reload# Enable start on boot and start service immediatlysudo systemctl enable kiwix.service && sudo systemctl start kiwix.service

This should do it ! Have fun with your custom static sites.