Kiwix-serve: quick start

.env

KIWIX_FILES=/path/to/zim/files
KIWIX_PORT=2080

README.md

Quick setup for a Kiwix server

What is this?

Kiwix is an application for browsing content packaged from websites like Wikipedia (and other Mikimedia projects), Stack Overflow (and other Q&A websites from Stack Exchange) and many other educational resources without reaching out to the global network. Helpful in areas that are particularly remote or restrictive in terms of traffic or censorship.

This is a setup of Kiwix focused on ease of installation and maintenance using Docker.

🔗 See the website of the Kiwix project for more details

What do I need to run this?

• You will need a supported (amd64, armv7, arm64) hardware platform and enough disk space to store ZIM files
• Your hardware platform should have Linux, Docker and Docker Compose installed
• Download ZIM content files from the internet, e. g. Kiwix Library
  • Prefer BitTorrent downloads (.torrent files or magnet links) for larger files to distribute the load
  • Expect BitTorrent downloads to work only for the more popular files
• Gather your ZIM files in a certain folder on the device
• Create a new folder for configurations somewhere (e. g. kiwix-serve in your home folder)
  • Copy over docker-compose.yaml from here into that folder with no changes
  • Copy over .env from here and replace the values inside
    • KIWIX_FILES needs to point at a folder that contains ZIM files
    • KIWIX_PORT can stay as-is, but feel free to modify according to your preferences
• Run docker-compose up -d to start
  • Startup might take a while depending on how many ZIM files you have and how big they are
  • You can also run docker-compose logs -f to see the output of the application, use Ctrl+C or Ctrl+\ to exit
• Navigate to http://$IP_ADDRESS:$KIWIX_PORT to see your content
  • Replace $IP_ADDRESS with the IP address of your machine
  • Replace $KIWIX_PORT with the number defined in your .env file
  • E. g. from the same machine and with the already specified port this could be http://127.0.0.1:2080

---

How is this better than the official Docker way?

• No redundant list of ZIM files neither in docker-compose.yml or in any XML files you'd have to populate using kiwix-manage — just drop new files into the folder and restart the container for them to be picked up automatically
• Host mount is read-only, which is a minor security improvement

docker-compose.yml

version: '3.2'
services:
  main:
    image: kiwix/kiwix-serve:3.2.0-1
    entrypoint: ["/usr/bin/dumb-init", "--", "sh", "-c", "/usr/local/bin/start.sh *.zim"]
    volumes: ["$KIWIX_FILES:/data:ro"]
    ports: ["$KIWIX_PORT:80"]