kiwix-serve 3.8.2

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick kiwix-serve 3.8.2 on Ubuntu 24.04 as the software version and select your Region. Then choose Launch through EC2.

Choose m5.large, your key pair, a security group as described above, and a subnet.

The AMI brings an 8 GiB root volume. ZIM archives can be large: a full English Wikipedia with pictures is over 100 GB. Raise the root volume under Configure storage, or attach a data volume later (Step 7), to fit the books you plan to serve.

Alternatively, launch with the AWS CLI. Replace the values in angle brackets. This command sets the root volume to 50 GiB:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=50,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=kiwix}]'

Version SSH user

kiwix-serve 3.8.2 on Ubuntu 24.04 ubuntu

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

First boot generates the certificate and the password, then publishes the site. This takes a few seconds. Check that the services are running:

systemctl is-active kiwix-serve-firstboot kiwix-serve nginx

active active active

Only SSH (22) and nginx (80, 443) listen on the network. kiwix-serve (8080) listens on loopback. The other two listeners are Ubuntu's local DNS resolver:

sudo ss -lntp | awk 'NR>1 {print $4}' | sort -u

0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:8080 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::]:80

If nginx serves nothing, first boot has not finished or has failed. When first boot fails, the site is never published. Check systemctl status kiwix-serve-firstboot and journalctl -u kiwix-serve-firstboot.

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

The file is readable by root only. It holds the address and this instance's sign-in:

# kiwix-serve - this instance's library sign-in (HTTP Basic Auth), generated on this instance; unique to it. # Open KIWIX_URL in a browser (the certificate is self-signed until you install your own; see the guide) and sign in. # Rotate the password with:
sudo kiwix-reset-password Change the served name:
sudo kiwix-set-hostname <name>
# Guide: https://secureanycloud.com/stacks/kiwix-serve-3-8-2/ KIWIX_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/ KIWIX_HTTP_USER=<KIWIX_HTTP_USER> KIWIX_BASIC_AUTH_PASSWORD=<KIWIX_BASIC_AUTH_PASSWORD> KIWIX_HEALTHZ=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/healthz

The URL uses the instance's public DNS name from EC2 instance metadata. The certificate also names the public and private IP addresses, so https://<public-ip>/ works too. To serve the library under your own DNS name, see Step 9.

You can verify the sign-in from the command line. The check signs in through nginx exactly as a browser does. An anonymous request and a wrong password are refused. This instance's password opens the library, the catalog, an article and a search:

sudo kiwix-verify.sh

kiwix: anonymous 401, wrong password 401, instance password 200 (library, catalog, article wikipedia_en_climate-change_mini_2026-10, search) KIWIX_ROUNDTRIP_OK

Open the KIWIX_URL in your browser. The certificate is self-signed, so your browser asks you to confirm it the first time. Alternatively, install your own certificate (Step 9).

The browser then asks for a user name and password. Enter KIWIX_HTTP_USER and KIWIX_BASIC_AUTH_PASSWORD from Step 4.

The library opens with every book on the instance. Filter by language or category, or search the titles.

Open a book to read it in the built-in reader. The bar at the top returns to the library, opens a random article and searches the book you are reading.

Search runs against the full text of the book, using the index built into the ZIM file. It lists matching articles with a snippet:

The same library is also available as an OPDS catalog at https://<your-host>/catalog/v2/entries, with the same sign-in. Kiwix desktop and mobile apps and other OPDS readers can browse it.

The library lives in /var/lib/kiwix. Its manifest, library.xml, lists the books that kiwix-serve offers, and kiwix-serve reloads it automatically when it changes. Find ZIM files in the Kiwix library or at download.kiwix.org.

The directory and files belong to root and are readable by the kiwix account, which can read but never change them.

To add a book, use the commands below. This example is a small Wikipedia selection. Use any ZIM file you like:

cd /var/lib/kiwix
sudo curl -fLO https://download.kiwix.org/zim/wikipedia/wikipedia_en_ray-charles_maxi_2026-08.zim
sudo chown root:kiwix wikipedia_en_ray-charles_maxi_2026-08.zim && sudo chmod 0640 wikipedia_en_ray-charles_maxi_2026-08.zim
sudo kiwix-manage /var/lib/kiwix/library.xml add /var/lib/kiwix/wikipedia_en_ray-charles_maxi_2026-08.zim

To list the books, and to remove one by the id that show prints, use the commands below. Delete the file afterwards:

sudo kiwix-manage /var/lib/kiwix/library.xml show | grep -E '^(id|path|title):'

id: 0f31ce81-5ccc-a70c-bab7-4e40276eb7f4 path: /var/lib/kiwix/wikipedia_en_climate-change_mini_2026-10.zim title: Climate change by Wikipedia

sudo kiwix-manage /var/lib/kiwix/library.xml remove <book-id>

For large collections, attach an EBS volume, format it and mount it at /var/lib/kiwix. Copy the existing files across first. Add an /etc/fstab entry by UUID with the nofail option. Keep the owner root:kiwix and the modes 0750 for the directory and 0640 for the files.

To generate a new password, for example after sharing the old one, run the command below. The new password is written to /root/kiwix-serve-credentials.txt, and the old one stops working at once:

sudo kiwix-reset-password

To give several people their own sign-in, add lines to /etc/nginx/kiwix.htpasswd in the same name:hash form. Create a hash with openssl passwd -6, which prompts for the password. Then run sudo systemctl reload nginx.

To publish the library without a sign-in, remove the two auth_basic lines from /etc/nginx/sites-available/sac-kiwix and reload nginx. Do this only if everyone who can reach port 443 may read every book.

Point a DNS record at the instance. An Elastic IP keeps the address across stop and start. Then tell the instance its name. This creates a new self-signed certificate for that name, updates the nginx host rule and the address in the credentials file, and keeps the name across reboots:

sudo kiwix-set-hostname library.example.com

To use a certificate from a public authority instead, replace /etc/ssl/kiwix/kiwix.crt (full chain) and /etc/ssl/kiwix/kiwix.key (mode 0600, owned by root) with your own, then run sudo systemctl reload nginx. Running kiwix-set-hostname again later replaces them with a new self-signed pair.

Every service is enabled, so the library returns after a reboot or a stop and start. If the public address changes, the next boot re-issues the certificate and the address for the new name, unless you set your own name in Step 9. Unattended security upgrades keep the operating system and nginx patched:

systemctl is-enabled kiwix-serve kiwix-set-host nginx unattended-upgrades

enabled enabled enabled enabled

kiwix-serve itself is the official static release from the Kiwix project. To move to a newer release later, download kiwix-tools_linux-x86_64-musl-<version>.tar.gz from download.kiwix.org and check its checksum. Replace the three files in /usr/local/bin, then run sudo systemctl restart kiwix-serve.

The books are plain ZIM files that you can download again. The only state is /var/lib/kiwix/library.xml and any books you added. An EBS snapshot of the volume that holds /var/lib/kiwix (or AWS Backup on the instance) keeps both. For a file-level copy, run:

sudo tar czf kiwix-library-backup.tar.gz -C /var/lib/kiwix library.xml