Retired Techie

Introduction

Today we will set up a Kiwix server on a Debian Linux container (LXC) using Proxmox VE. Kiwix is an application that allows users to view offline websites, such as Wikipedia, utilizing the ZIM file format.

This setup involves four key tasks:

• Building a Linux container: Operating environment for Kiwix.
• Installing kiwix-tools: Acquiring required Kiwix software.
• Creating a Kiwix Systemd service: Automate System management of Kiwix.
• Downloading ZIM files: Files containing offline content

With this configuration, Local Area Network (LAN) users can access Kiwix, viewing downloaded content offline. This is useful for a couple of reasons.

• Access content when Internet connectivity is questionable.
• Access local coin private, rather than browsing the Internet.

Many of the tutorials for Kiwix recommend using Docker, but I prefer to not add an additional layer when my network servers are already running on Virtual Machines (VM) or Linux containers (LXC). Docker is beneficial in environments with a single Operating System (OS), but its complexity is, in many instances, not necessary for virtualization setups.

In this video, I will create a Debian 13 LXC to host Kiwix. While there’s a kiwix-tools package available in the Debian repositories, it is outdated, with no newer version available in either the Experimental (SID) or back-ports repositories. Therefore, we will obtain the latest version directly from the Kiwix website. However, please note that, unlike the Debian package, this version does not include man pages in the archive. Also this version will not be3 updated by the Debian package manager.

Although a Debian package exists, it wasn’t designed for automated operations. We will need to create a systemd service file for the kiwix-serve program. Due to the version differences and the need for automation, we will treat this installation as non-Debian in this tutorial.

Additionally, our server will not have a GUI or browser. To navigate this limitation, we will use wget to pull both the application and ZIM files for Kiwix. Additionally, some minor configuration (via command line) will be required along the way. Since this is my first time using the application it promises to be an interesting endeavor, so stick around to see how it works out!

I also want to clarify that this setup differs from a Kiwix hot-spot. With a hot-spot, you connect your devices to its Wi-Fi, limiting other network usage. In contrast, this method will run over your existing Local Area Network (LAN), allowing for simultaneous internet connectivity. I won’t argue which approach is better, as it truly depends on the situation.

Setup LXC

We will use the Debian 13 image file for our LXC setup. This process has been covered in several of my other videos, so I won’t go into detail here.

You will need to acquire some basic information prior to installation:

• LXC Name
• LXC ID (Proxmox ID)
• Root User and Password
• Non-Root User and Password
• LXC Specifications: 1 GB memory, 2 CPU cores, 512 GB storage

Updating the Image: After creation, the first step is to update and upgrade the image. Note that by default we need to use the Porxmox console initially, and there is no normal user and sudo is not installed yet. So we need to be logged in as root at this point.

apt update
apt upgrade

The Debian LXC comes with a few tools already installed by default; openssh-server, tar, gzip, and wget. But we will also want to add sudo.

apt install sudo

Next we need to create our non root user, and add them to the sudo group.

useradd -m -c “User Name” -s /bin/bash <user>
passwd <user>
usermod -aG sudo <user>

At this point, we can log in via SSH, eliminating the need for the Proxmox terminal. Note that logging in via SSH means we are operating under our unprivileged user rather than root. Thus, we will need to use sudo for commands that affect areas outside our home directory.

Getting Kiwix-Tools

To retrieve the application archive, visit get.kiwix.org and navigate to Applications > Kiwix Server. We want to download the GNU/Linux amd64 version. Right-click the link and copy it, as we will paste this into wget on our server.

Use the following command to download Kiwix-Tools:

wget https://download.kiwix.org/release/kiwix-tools/kiwix-tools_linux-x86_64.tar.gz

The file is tarred and gzipped. We will un-archive it into our home directory, creating its own folder:

tar -xvzf kiwix-tools_linux-x86_64.tar.gz

We will want to download at least one ZIM file. For our initial test, we will start with a smaller file that won’t take long to download. One convenient source for ZIM files is library.kiwix.org. While there are other sources available, we will use it for now. Choose any file you like, keeping in mind that larger ZIM files will result in longer downloads. For this tutorial, we will use:

wget https://download.kiwix.org/zim/zimit/fas-military-medicine_en_2025-06.zim

Initially, all our testing will be done in our home directory as a standard user, so we won’t need sudo permissions at this stage. Once we confirm that the tools work and set up our actual working environment, things will become a bit more complex.

Testing Kiwix-Tools

We will create a local folder structure in our home directory to test Kiwix-Tools. This structure will reflect our final working setup as closely as possible.

Creating the Folder Structure: First, use the mkdir (make directory) command to create two folders: kiwix and kiwixlibrary.

mkdir kiwix
mkdir kiwixlibrary

Moving Kiwix Tools: Next, we need to move the Kiwix tools to our new kiwix folder using the mv (move) command. After that, we can remove the folder that was created when we uncompressed the archive using the rm (remove) command with the –roption for recursion.

mv kiwix-tools_linux-x86_64-3.8.2/kiwix-* kiwix/
rm -r kiwix-tools_linux-x86_64-3.8.2

Moving the ZIM file: Now, let’s move our ZIM file to the kiwixlibrary folder. Again, we will use the mv command.

mv <file>.zim kiwixlibrary/

Creating the Library File: Now, we will use the kiwix-manage tool to create an XML library file in our kiwix folder that points to all our ZIM files. Note that while it uses the XML extension, this is definitely not a traditional XML file, so avoid trying to edit it by hand.

kiwix/kiwix-manage kiwix/zimlib.xml add kiwixlibrary/<file>.zim

Starting Kiwix: After creating the library file, we can start Kiwix to see if it is functioning correctly. We will use a port number greater than 1024. Although well-known ports (below 1024), like 80, are technically possible, the complications they bring are not worth it at this stage of testing.

kiwix/kiwix-serve --port=8080 --library kiwix/zimlib.xml

When starting manually, you should see output in the terminal, including any error messages. One common error is failing to find the library, which usually results from path issues, so be sure to review your commands carefully if Kiwix does not start successfully.

Setup Kiwix as a Service

Assuming everything went well, use “Ctrl + C” to exit Kiwix before configuring it up to run as a service. For this we need to complete several steps.

• Move folders containing kiwix tools and zim files
• Create a non-login Kiwix user
• Set ownership and permissions
• recreate our library file
• create a systemd service file

Yes that sounds like a lot, but let’s take it one step at a time.

Moving Kiwix folders: First, let’s move our Kiwix folders to their permanent locations, following the Linux File System Hierarchy Standard. This helps maintain compliance with Kiwix Install, without Docker!standard practices (unlike most Linux distros, lets at least try to be compliant).

sudo mv /home/<user>/kiwix /opt/kiwix
sudo mv /home/<user>/kiwixlibrary /srv/kiwixlibrary

According to the standard, non disto programs should go in the /opt folder, and server data should go in the /srv folder.

Creating Kiwix User: Lets create our kiwix user.

sudo useradd -r -d /opt/kiwix -c “kiwix User” -s /usr/sbin/nologin kiwix

• The -r option creates a system user (with a user and group ID below 1000).
• The -d option specifies a home directory at the location we provide (instead of the default created by the -m option).
• The -c option adds a comment (username).
• The -s option sets the login shell, which in this case does not allow for login.

Setting Ownership: Lets set ownership of our new folder structure.

chown -R kiwix:kiwix /opt/kiwix
chown -R kiwix:kiwix /srv/kiwixlibrary

Rebuild Library: We want to rebuild our library.xml file with our new locations.

sudo /opt/kiwix/kiwix-manage /opt/kiwix/zimlib.xml add /srv/kiwixlibrary/<file>.zim

Create Systemd Service File: We can create our systemd service file to ensure Kiwix starts automatically at boot. Use your preferred text editor to create the file at /etc/systemd/system/kiwix.service:. Use your favorite text editor (note, you will need to interpret if you are using different file paths than I am).

[Unit]
Description=kiwix Zim Server
After=network.target

[Service]
User=kiwix
Group=kiwix
ExecStartPre=/bin/sleep 10
ExecStart=/bin/kiwix-serve --port 8080 --library /opt/kiwix/zimlib.xml

[Install]
WantedBy=multi-user.target

I have covered all the options in this file in other videos, which I will link in the description.

Additional note: If you want to use a port number below 1024, then the following two lines need to be included in the [Service] section of the systemd service file.

AmbientCapabilities=CAP_NET_BIND_SERVICE 
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

Run Kiwix as a Service

Now we will test our ¹Kiwix service. The first step is to make the operating system aware of the new kiwix.servicefile. We can do this by either rebootin²g the system or restarting the daemon service:

sudo systemctl daemon-reload

Check the Status: Let's check the status of our new service to ensure the system recognizes it:

sudo systemctl start kiwix.service

Enable at Boot: We want to enable the service so that it starts automatically at boot:

sudo systemctl enable iwix.service

Start Service: We want to actually start the service

sudo systemctl start kiwix.service

Once the service is started, you can point your web browser to the appropriate address, and the title page should load successfully.

Adding more zim files

We will setup a “no login” system user specifically for kiwix. This can become a bit complex when updating our ZIM files and corresponding ZIM Library. Basically we may see permission errors for files and directories owned by the “no login” user.

To get around this we use the sudo command with the -u option, allowing us to specify a user to operate as.

sudo -u kiwix /opt/kiwix/kiwix-manage zimlib.xml add /srv/kiwixlibrary/*.zim

This command might seem a bit long. Since we are using a wildcard character, *.zim, the command will pick up all zim files in the kiwixlibrary directory. This gives us a few choices to shorten it.

• cd into the /opt/kiwix directory, eliminating the need for a full command path cd /opt/kiwix
  sudo -u kiwix kiwix-manage zimlib.xml add /srv/kiwixlibrary/*.zim
  
• create an alias to run the commands alias kiwixupdate = /opt/kiwix/kiwix-manage zimlib.xml add /srv/kiwixlibrary/*.zim
  sudo -u kiwix kiwixupdate
  
• Make an executable script (kiwixupdate.sh for example) file to run the command #!/bin/bash
  sudo -u kiwix /opt/kiwix/kiwix-manage zimlib.xml add /srv/kiwixlibrary/*.zim

Additional Thoughts

Some of the ZIM files can be pretty large and take awhile to download (depending on internet connection speed). It may be advantages to detach the download command form the terminal and run it in the background, so as not to hold up other work while the zim file is downloading (the entire wiki is over 100 GB).

nohup sudo -u kiwix wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim &

Epilogue

In this post we have been working with kiwix. It is an application, or suit of tools to allow offline usage of ZIM files, for example wiki pages.

We did not do the recommended docker installation. Instead we downloaded the kiwix tools directly into an LXC container we created, and ran them from there. We basically created a kiwix server on our LAN, making off line content available to all our users.

The two big advantages to this are access to the material if the internet ever goes down, and maintaining some level of privacy by browsing off line content that big tech or big brother cannot track.