Posted on • Edited on
Self-Hosting Wikipedia (and other sites ...) with Kiwix
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.
Top comments(0)
For further actions, you may consider blocking this person and/orreporting abuse