kiwix-serve Offline Content Server on AWS User Guide

Overview

This image runs kiwix-serve 3.8.2 (from the official statically linked kiwix-tools release) on Ubuntu 24.04 LTS. kiwix-serve is a single, self-contained HTTP server that publishes offline content archives packaged in the open ZIM format through a built-in library and reader web interface. A single ZIM file can hold an entire offline copy of Wikipedia, Wiktionary, Stack Exchange, Project Gutenberg, a wiki, a documentation set or any other web content, browsable and full-text searchable from a normal web browser with no internet connection required.

The server runs as an unprivileged kiwix system account under a systemd service that starts it on boot and restarts it on failure. It reads the ZIM library from /var/lib/kiwix and binds to the loopback address 127.0.0.1:8080 by design, so it is never exposed directly.

An nginx reverse proxy on port 80 fronts kiwix-serve and enforces HTTP Basic Authentication. Because kiwix-serve has no authentication of its own, this image is secure by default: on the first boot of every deployed instance a one-shot service generates a fresh per-instance Basic Auth password and writes it to /root/kiwix-serve-credentials.txt (mode 0600, readable only by root). No password is baked into the image, and two instances launched from the same AMI never share one. A lightweight unauthenticated /healthz endpoint is available for load balancers and monitoring.

The image ships with a small sample archive, Wikipedia 100 (the 100 most-read English Wikipedia articles, wikipedia_en_100_mini), so the library has real content to browse on first boot. The article text and media are Wikipedia content under the Creative Commons Attribution-ShareAlike licence and remain freely redistributable, with the publisher and licence shown on every book card and article. You can add your own ZIM archives at any time.

The default security group for this listing opens port 22 (SSH) and port 80 (HTTP) only.

Prerequisites

• An AWS account subscribed to this product in AWS Marketplace.
• An EC2 key pair in your target region for SSH access.
• A security group allowing inbound TCP 22 (SSH) from your IP and TCP 80 (HTTP) from your users.
• Recommended instance type: m5.large or larger.

Connecting to your instance

SSH in as the default login user for your operating system variant, using the key pair you launched with.

Step 1 - Launch from the AWS Marketplace console

1. Open the product page in AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration.
2. Select the kiwix-serve 3.8.2 on Ubuntu 24.04 delivery option and your region, then Continue to Launch.
3. Choose your instance type, VPC/subnet, key pair and the security group described above, and launch.

Step 2 - Launch from the AWS CLI

Replace the AMI ID with the one shown on the product's launch page for your region, and use your own key pair and security group.

aws ec2 run-instances \
  --image-id ami-xxxxxxxxxxxxxxxxx \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=kiwix-serve}]'

Step 3 - Connect to your instance

ssh -i your-key.pem ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

kiwix-serve and nginx both start on boot. Confirm they are active:

systemctl is-active kiwix-serve.service nginx.service

Both report active. Check the installed version:

/usr/local/bin/kiwix-serve --version

kiwix-tools 3.8.2

libkiwix 14.2.0

kiwix-serve binds to loopback only; nginx listens on port 80:

sudo ss -ltnp | grep -E '127.0.0.1:8080|:80 '

LISTEN 0 128 127.0.0.1:8080 0.0.0.0:* users:(("kiwix-serve",pid=2664,fd=3))
LISTEN 0 511       0.0.0.0:80 0.0.0.0:* users:(("nginx",...))

Step 5 - Retrieve the per-instance credentials

The Basic Auth password is generated on this instance's first boot and stored in a root-only file. Read it over SSH:

sudo cat /root/kiwix-serve-credentials.txt

# kiwix-serve - Per-VM Credentials
# Generated on first boot by kiwix-serve-firstboot.service
#
KIWIX_HTTP_USER=admin
KIWIX_BASIC_AUTH_PASSWORD=<generated-per-instance>
KIWIX_URL=http://<instance-public-ip>/
KIWIX_HEALTHZ=http://<instance-public-ip>/healthz
KIWIX_LOCAL_HTTP=http://127.0.0.1:8080/

The unauthenticated health-check endpoint answers without a password, so load balancers and monitoring can probe it:

curl -s -o /dev/null -w 'healthz -> HTTP %{http_code}\n' http://127.0.0.1/healthz

healthz -> HTTP 200

Any other request without valid credentials is refused with HTTP 401, proving the library is not open:

curl -s -o /dev/null -w 'library (no auth) -> HTTP %{http_code}\n' http://127.0.0.1/

library (no auth) -> HTTP 401

Step 6 - Open the library

Browse to http://<instance-public-ip>/ and sign in with the username (admin) and the per-instance password from the credentials file. The library welcome page lists the bundled Wikipedia 100 archive as a book card showing its title, description and language.

Click the book card to open it in the reader. The reader shows the archive's visual article index, with the book title, a random-article button and a search box in the top bar - all served locally from the ZIM with no internet connection.

Step 7 - Read an article

Open any article to read it in the built-in viewer, complete with formatting, images and infoboxes, exactly as it appears on the live site but served entirely offline.

Step 8 - Search the archive

Type a term into the reader's search box for instant suggestions, or press Enter for a full-text search across the whole archive, ranked by relevance with a short snippet from each matching article. This confirms the ZIM is indexed and searchable.

You can confirm the content catalog over the loopback interface too:

curl -s -o /dev/null -w 'catalog -> HTTP %{http_code}\n' http://127.0.0.1:8080/catalog/v2/entries

catalog -> HTTP 200

Step 9 - Add your own ZIM content

Download any ZIM archive from the Kiwix library (Wikipedia in many languages, Wiktionary, WikiHow, medical and educational libraries, and more) into /var/lib/kiwix, then register it with kiwix-manage. The running server watches the library and picks up the new archive automatically - no restart needed.

# Example: download a ZIM and register it (replace the URL and filename with your own).
sudo curl -fSL -o /var/lib/kiwix/your-content.zim \
  https://download.kiwix.org/zim/other/your-content.zim
sudo kiwix-manage /var/lib/kiwix/library.xml add /var/lib/kiwix/your-content.zim
sudo chown kiwix:kiwix /var/lib/kiwix/your-content.zim /var/lib/kiwix/library.xml

To remove the bundled sample later, delete its file and rebuild the library the same way. Larger archives (full Wikipedia is tens of gigabytes) benefit from a larger root volume - resize the EBS volume and grow the filesystem before downloading.

Step 10 - Make the library public (optional)

The library is protected by Basic Auth by default. To serve it openly (for example on a trusted private network), remove the two auth_basic directives from the nginx site and reload nginx, then confirm your security group allows the traffic.

sudo nano /etc/nginx/sites-available/cloudimg-kiwix   # remove the two auth_basic lines
sudo nginx -t
sudo systemctl reload nginx

To restrict access to specific clients instead, keep Basic Auth and/or narrow the inbound rule on port 80 in your security group to your own CIDR (your-cidr).

Step 11 - Service management

kiwix-serve and nginx are managed by systemd:

sudo systemctl status kiwix-serve
sudo systemctl status nginx
sudo journalctl -u kiwix-serve -e

Backup and maintenance

• Content lives in /var/lib/kiwix (the ZIM files and library.xml). Back up that directory to preserve your library; ZIM files are self-contained and portable.
• Credentials are in /root/kiwix-serve-credentials.txt. To rotate the Basic Auth password, regenerate the nginx htpasswd entry for the admin user and reload nginx.
• OS updates: the image ships fully patched with unattended security updates enabled. Apply the latest packages at any time with your normal patch process and reboot if a new kernel is installed.

Notes on licensing and trademarks

kiwix-serve is distributed under the GNU General Public License version 3. The bundled sample archive is Wikipedia content under the Creative Commons Attribution-ShareAlike 3.0 licence and is freely redistributable with attribution, which the reader preserves on every book card and article. cloudimg is not affiliated with or endorsed by the Kiwix or openZIM project. All product and company names are trademarks or registered trademarks of their respective holders.

Support

This image is backed by 24/7 cloudimg support covering deployment, first-boot behaviour, the nginx authentication proxy and adding or replacing ZIM content. Contact support through the details on the cloudimg listing page.