Solved. How to setup Kiwix Server in Truenas?

TrueNAS General
1

Most of requests to setup Kiwix Server were not answered…most of them without log files.

I setup the Kiwi Server, run into issue, copied *.zim file into /data directory …but nothing changed.

Following logs I received:

Permission:

Application Name:kiwix-serverContainer ID:6f146026a2bc2cf2dbffd8bf0a4ad3ee141c87e3b064e7267390923e7f5c5efa
2026-05-08 15:15:21.683601+00:00🚀 Starting permissions configuration...
2026-05-08 15:15:21.683797+00:00--------------------------- data ---------------------------
2026-05-08 15:15:21.683833+00:00⏭️ Path is not empty, no changes will be applied
2026-05-08 15:15:21.683858+00:00============================================================
2026-05-08 15:15:21.683881+00:002026-05-08T15:15:21.683881748Z
2026-05-08 15:15:21.683921+00:002026-05-08T15:15:21.683921326Z
2026-05-08 15:15:21.683944+00:00⏱️ Total time taken: 1.12ms
2026-05-08 15:15:21.683966+00:00🎉 All permissions configured successfully!

Kiwi-Serve:

Application Name:kiwix-serverContainer ID:b8af1ae722db0006c3522c89fb66f58349e8f487096695c37442c1be263ec447
2026-05-08 15:17:13.732618+00:00/usr/local/bin/kiwix-serve --port=30236
2026-05-08 15:17:13.800757+00:00Arguments did not match expected patterns
2026-05-08 15:17:13.800911+00:00Deliver ZIM file(s) articles via HTTP
2026-05-08 15:17:13.800940+00:002026-05-08T15:17:13.800940737Z
2026-05-08 15:17:13.800963+00:00Usage:
2026-05-08 15:17:13.800985+00:00kiwix-serve [options] ZIMPATH ...
2026-05-08 15:17:13.801045+00:00kiwix-serve [options] (-l | --library) LIBRARYPATH
2026-05-08 15:17:13.801072+00:00kiwix-serve -h | --help
2026-05-08 15:17:13.801094+00:00kiwix-serve -V | --version
2026-05-08 15:17:13.801116+00:002026-05-08T15:17:13.801116961Z
2026-05-08 15:17:13.801138+00:00Mandatory arguments:
2026-05-08 15:17:13.801173+00:00LIBRARYPATH  XML library file path listing ZIM file to serve. To be used only with the --library argument."
2026-05-08 15:17:13.801197+00:00ZIMPATH      ZIM file path(s)
2026-05-08 15:17:13.801220+00:002026-05-08T15:17:13.801220040Z
2026-05-08 15:17:13.801242+00:00Options:
2026-05-08 15:17:13.801264+00:00-h --help                               Print this help
2026-05-08 15:17:13.801299+00:00-a <pid> --attachToProcess=<pid>        Exit if given process id is not running anymore [default: 0]
2026-05-08 15:17:13.801325+00:00--catalogOnly                           Serve only the library catalog
2026-05-08 15:17:13.801347+00:00--contentServerURL=<url>                Root URL of the server serving ZIM content for this library
2026-05-08 15:17:13.801383+00:00-d --daemon                             Detach the HTTP server daemon from the main process
2026-05-08 15:17:13.801409+00:00-i <address> --address=<address>        Listen only on the specified IP address. Specify 'ipv4', 'ipv6' or 'all' to listen on all IPv4, IPv6 or both types of addresses, respectively [default: all]
2026-05-08 15:17:13.801453+00:00-M --monitorLibrary                     Monitor the XML library file and reload it automatically
2026-05-08 15:17:13.801477+00:00-m --nolibrarybutton                    Don't print the builtin home button in the builtin top bar overlay
2026-05-08 15:17:13.801501+00:00-n --nosearchbar                        Don't print the builtin bar overlay on the top of each served page
2026-05-08 15:17:13.801533+00:00-b --blockexternal                      Prevent users from directly accessing external links
2026-05-08 15:17:13.801557+00:00-p <port> --port=<port>                 Port on which to listen to HTTP requests [default: 80]
2026-05-08 15:17:13.801580+00:00-r <root> --urlRootLocation=<root>      URL prefix on which the content should be made available [default: /]
2026-05-08 15:17:13.801614+00:00-s <limit> --searchLimit=<limit>        Maximun number of zim in a fulltext multizim search [default: 0]
2026-05-08 15:17:13.801640+00:00-t <threads> --threads=<threads>        Number of threads to run in parallel [default: 4]
2026-05-08 15:17:13.801665+00:00-v --verbose                            Print debug log to STDOUT
2026-05-08 15:17:13.801700+00:00-V --version                            Print software version
2026-05-08 15:17:13.801730+00:00-z --nodatealiases                      Create URL aliases for each content by removing the date
2026-05-08 15:17:13.801755+00:00-c <path> --customIndex=<path>          Add path to custom index.html for welcome page
2026-05-08 15:17:13.801790+00:00-L <limit> --ipConnectionLimit=<limit>  Max number of (concurrent) connections per IP [default: 0] (recommended: >= 6)
2026-05-08 15:17:13.801816+00:00-k --skipInvalid                        Startup even when ZIM files are invalid (those will be skipped)
2026-05-08 15:17:13.801841+00:002026-05-08T15:17:13.801841150Z
2026-05-08 15:17:13.801864+00:00Documentation:
2026-05-08 15:17:13.801897+00:00Source code   https://github.com/kiwix/kiwix-tools
2026-05-08 15:17:13.801922+00:00More info     https://wiki.kiwix.org/wiki/Kiwix-serve
2026-05-08 15:17:13.801946+00:00https://kiwix-tools.readthedocs.io/en/latest/kiwix-serve.html
2026-05-08 15:17:13.801969+00:002026-05-08T15:17:13.801969175Z
2026-05-08 15:17:13.802124+00:00Here is the content of /data:
2026-05-08 15:17:13.803695+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 15:17:14.683091+00:00/usr/local/bin/kiwix-serve --port=30236
2026-05-08 15:17:14.750450+00:00Arguments did not match expected patterns
2026-05-08 15:17:14.750584+00:00Deliver ZIM file(s) articles via HTTP
2026-05-08 15:17:14.750650+00:002026-05-08T15:17:14.750650078Z
2026-05-08 15:17:14.750675+00:00Usage:
2026-05-08 15:17:14.750697+00:00kiwix-serve [options] ZIMPATH ...
2026-05-08 15:17:14.750719+00:00kiwix-serve [options] (-l | --library) LIBRARYPATH
2026-05-08 15:17:14.750742+00:00kiwix-serve -h | --help
2026-05-08 15:17:14.750775+00:00kiwix-serve -V | --version
2026-05-08 15:17:14.750798+00:002026-05-08T15:17:14.750798392Z
2026-05-08 15:17:14.750820+00:00Mandatory arguments:
2026-05-08 15:17:14.750843+00:00LIBRARYPATH  XML library file path listing ZIM file to serve. To be used only with the --library argument."
2026-05-08 15:17:14.750867+00:00ZIMPATH      ZIM file path(s)
2026-05-08 15:17:14.750903+00:002026-05-08T15:17:14.750903547Z
2026-05-08 15:17:14.750928+00:00Options:
2026-05-08 15:17:14.750952+00:00-h --help                               Print this help
2026-05-08 15:17:14.750975+00:00-a <pid> --attachToProcess=<pid>        Exit if given process id is not running anymore [default: 0]
2026-05-08 15:17:14.751013+00:00--catalogOnly                           Serve only the library catalog
2026-05-08 15:17:14.751039+00:00--contentServerURL=<url>                Root URL of the server serving ZIM content for this library
2026-05-08 15:17:14.751063+00:00-d --daemon                             Detach the HTTP server daemon from the main process
2026-05-08 15:17:14.751087+00:00-i <address> --address=<address>        Listen only on the specified IP address. Specify 'ipv4', 'ipv6' or 'all' to listen on all IPv4, IPv6 or both types of addresses, respectively [default: all]
2026-05-08 15:17:14.751127+00:00-M --monitorLibrary                     Monitor the XML library file and reload it automatically
2026-05-08 15:17:14.751152+00:00-m --nolibrarybutton                    Don't print the builtin home button in the builtin top bar overlay
2026-05-08 15:17:14.751191+00:00-n --nosearchbar                        Don't print the builtin bar overlay on the top of each served page
2026-05-08 15:17:14.751216+00:00-b --blockexternal                      Prevent users from directly accessing external links
2026-05-08 15:17:14.751240+00:00-p <port> --port=<port>                 Port on which to listen to HTTP requests [default: 80]
2026-05-08 15:17:14.751277+00:00-r <root> --urlRootLocation=<root>      URL prefix on which the content should be made available [default: /]
2026-05-08 15:17:14.751304+00:00-s <limit> --searchLimit=<limit>        Maximun number of zim in a fulltext multizim search [default: 0]
2026-05-08 15:17:14.751340+00:00-t <threads> --threads=<threads>        Number of threads to run in parallel [default: 4]
2026-05-08 15:17:14.751369+00:00-v --verbose                            Print debug log to STDOUT
2026-05-08 15:17:14.751391+00:00-V --version                            Print software version
2026-05-08 15:17:14.751416+00:00-z --nodatealiases                      Create URL aliases for each content by removing the date
2026-05-08 15:17:14.751454+00:00-c <path> --customIndex=<path>          Add path to custom index.html for welcome page
2026-05-08 15:17:14.751479+00:00-L <limit> --ipConnectionLimit=<limit>  Max number of (concurrent) connections per IP [default: 0] (recommended: >= 6)
2026-05-08 15:17:14.751518+00:00-k --skipInvalid                        Startup even when ZIM files are invalid (those will be skipped)
2026-05-08 15:17:14.751544+00:002026-05-08T15:17:14.751544404Z
2026-05-08 15:17:14.751567+00:00Documentation:
2026-05-08 15:17:14.751590+00:00Source code   https://github.com/kiwix/kiwix-tools
2026-05-08 15:17:14.751613+00:00More info     https://wiki.kiwix.org/wiki/Kiwix-serve
2026-05-08 15:17:14.751649+00:00https://kiwix-tools.readthedocs.io/en/latest/kiwix-serve.html
2026-05-08 15:17:14.751674+00:002026-05-08T15:17:14.751674655Z
2026-05-08 15:17:14.752349+00:00Here is the content of /data:
2026-05-08 15:17:14.754285+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 15:17:15.634364+00:00/usr/local/bin/kiwix-serve --port=30236
2026-05-08 15:17:15.701960+00:00Arguments did not match expected patterns
2026-05-08 15:17:15.702112+00:00Deliver ZIM file(s) articles via HTTP
2026-05-08 15:17:15.702147+00:002026-05-08T15:17:15.702147685Z
2026-05-08 15:17:15.702172+00:00Usage:
2026-05-08 15:17:15.702197+00:00kiwix-serve [options] ZIMPATH ...
2026-05-08 15:17:15.702270+00:00kiwix-serve [options] (-l | --library) LIBRARYPATH
2026-05-08 15:17:15.702297+00:00kiwix-serve -h | --help
2026-05-08 15:17:15.702322+00:00kiwix-serve -V | --version
2026-05-08 15:17:15.702346+00:002026-05-08T15:17:15.702346704Z
2026-05-08 15:17:15.702369+00:00Mandatory arguments:
2026-05-08 15:17:15.702412+00:00LIBRARYPATH  XML library file path listing ZIM file to serve. To be used only with the --library argument."
2026-05-08 15:17:15.702439+00:00ZIMPATH      ZIM file path(s)
2026-05-08 15:17:15.702462+00:002026-05-08T15:17:15.702462287Z
2026-05-08 15:17:15.702485+00:00Options:
2026-05-08 15:17:15.702508+00:00-h --help                               Print this help
2026-05-08 15:17:15.702548+00:00-a <pid> --attachToProcess=<pid>        Exit if given process id is not running anymore [default: 0]
2026-05-08 15:17:15.702578+00:00--catalogOnly                           Serve only the library catalog
2026-05-08 15:17:15.702603+00:00--contentServerURL=<url>                Root URL of the server serving ZIM content for this library
2026-05-08 15:17:15.702642+00:00-d --daemon                             Detach the HTTP server daemon from the main process
2026-05-08 15:17:15.702669+00:00-i <address> --address=<address>        Listen only on the specified IP address. Specify 'ipv4', 'ipv6' or 'all' to listen on all IPv4, IPv6 or both types of addresses, respectively [default: all]
2026-05-08 15:17:15.702713+00:00-M --monitorLibrary                     Monitor the XML library file and reload it automatically
2026-05-08 15:17:15.702835+00:00-m --nolibrarybutton                    Don't print the builtin home button in the builtin top bar overlay
2026-05-08 15:17:15.702867+00:00-n --nosearchbar                        Don't print the builtin bar overlay on the top of each served page
2026-05-08 15:17:15.702911+00:00-b --blockexternal                      Prevent users from directly accessing external links
2026-05-08 15:17:15.702937+00:00-p <port> --port=<port>                 Port on which to listen to HTTP requests [default: 80]
2026-05-08 15:17:15.702963+00:00-r <root> --urlRootLocation=<root>      URL prefix on which the content should be made available [default: /]
2026-05-08 15:17:15.703004+00:00-s <limit> --searchLimit=<limit>        Maximun number of zim in a fulltext multizim search [default: 0]
2026-05-08 15:17:15.703030+00:00-t <threads> --threads=<threads>        Number of threads to run in parallel [default: 4]
2026-05-08 15:17:15.703056+00:00-v --verbose                            Print debug log to STDOUT
2026-05-08 15:17:15.703096+00:00-V --version                            Print software version
2026-05-08 15:17:15.703127+00:00-z --nodatealiases                      Create URL aliases for each content by removing the date
2026-05-08 15:17:15.703154+00:00-c <path> --customIndex=<path>          Add path to custom index.html for welcome page
2026-05-08 15:17:15.703209+00:00-L <limit> --ipConnectionLimit=<limit>  Max number of (concurrent) connections per IP [default: 0] (recommended: >= 6)
2026-05-08 15:17:15.703240+00:00-k --skipInvalid                        Startup even when ZIM files are invalid (those will be skipped)
2026-05-08 15:17:15.703166+00:00Here is the content of /data:
2026-05-08 15:17:15.703264+00:002026-05-08T15:17:15.703264618Z
2026-05-08 15:17:15.703541+00:00Documentation:
2026-05-08 15:17:15.703580+00:00Source code   https://github.com/kiwix/kiwix-tools
2026-05-08 15:17:15.703607+00:00More info     https://wiki.kiwix.org/wiki/Kiwix-serve
2026-05-08 15:17:15.703633+00:00https://kiwix-tools.readthedocs.io/en/latest/kiwix-serve.html
2026-05-08 15:17:15.703733+00:002026-05-08T15:17:15.703733347Z
2026-05-08 15:17:15.705384+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim

metadata:

custom_app: false
human_version: 3.8.2_1.1.6
metadata:
  app_version: 3.8.2
  capabilities: []
  categories:
  - media
  changelog_url: https://github.com/kiwix/kiwix-tools/releases
  date_added: '2025-08-04'
  description: Kiwix Server is a ZIM compatible Web server.
  home: https://github.com/kiwix/kiwix-tools
  host_mounts: []
  icon: https://media.sys.truenas.net/apps/kiwix-server/icons/icon.svg
  keywords:
  - kiwix
  - server
  - zim
  - wiki
  last_update: '2026-04-27 11:53:24'
  lib_version: 2.3.4
  lib_version_hash: 2e3a8847308fb2eb0da046018f287c73822c094b5950a10377c3235794ff1242
  maintainers:
  - email: dev@truenas.com
    name: truenas
    url: https://www.truenas.com/
  name: kiwix-server
  run_as_context:
  - description: Container [kiwix-server] can run as any non-root user and group.
    gid: 568
    group_name: Host group is [apps]
    uid: 568
    user_name: Host user is [apps]
  screenshots: []
  sources:
  - https://github.com/kiwix/kiwix-tools
  title: Kiwix Server
  train: community
  version: 1.1.6
migrated: false
notes: '# Kiwix Server


  ## Security


  **Read the following security precautions to ensure that you wish to continue using
  this application.**


  ---


  ### Container: [kiwix-server]


  #### Running user/group(s)


  - User: 568

  - Group: 568

  - Supplementary Groups: apps


  ---


  ### Container: [permissions]


  **This container is short-lived.**


  #### Running user/group(s)


  - User: root

  - Group: root

  - Supplementary Groups: apps


  ---


  In case the container does not start, please ensure

  that there are ZIM files in the Data storage.


  ## Bug Reports and Feature Requests


  If you find a bug in this app or have an idea for a new feature, please file an
  issue at

  https://github.com/truenas/apps

  '
portals:
  Web UI: http://0.0.0.0:30236/
version: 1.1.6

If I remove the ZIM file data info field “Load specific ZIM Files” following error message will listed:

2026-05-08 16:47:33.108332+00:00/usr/local/bin/kiwix-serve --port=30236 wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:33.162346+00:00Unable to add the ZIM file 'wikipedia_de_climate-change_mini_2025-10.zim' to the internal library.
2026-05-08 16:47:33.163073+00:00Here is the content of /data:
2026-05-08 16:47:33.164446+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:33.912855+00:00/usr/local/bin/kiwix-serve --port=30236 wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:33.956673+00:00Unable to add the ZIM file 'wikipedia_de_climate-change_mini_2025-10.zim' to the internal library.
2026-05-08 16:47:33.957360+00:00Here is the content of /data:
2026-05-08 16:47:33.958564+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:34.681616+00:00/usr/local/bin/kiwix-serve --port=30236 wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:34.731697+00:00Unable to add the ZIM file 'wikipedia_de_climate-change_mini_2025-10.zim' to the internal library.
2026-05-08 16:47:34.732668+00:00Here is the content of /data:
2026-05-08 16:47:34.734246+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:35.666999+00:00/usr/local/bin/kiwix-serve --port=30236 wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:35.720580+00:00Here is the content of /data:
2026-05-08 16:47:35.720897+00:00Unable to add the ZIM file 'wikipedia_de_climate-change_mini_2025-10.zim' to the internal library.
2026-05-08 16:47:35.722634+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:36.911790+00:00/usr/local/bin/kiwix-serve --port=30236 wikipedia_de_climate-change_mini_2025-10.zim
2026-05-08 16:47:36.953728+00:00Unable to add the ZIM file 'wikipedia_de_climate-change_mini_2025-10.zim' to the internal library.
2026-05-08 16:47:36.953754+00:00Here is the content of /data:
2026-05-08 16:47:36.955202+00:00/data/wikipedia_de_climate-change_mini_2025-10.zim

Based on my less knowledge I ask to provide me due to log files.

Thank you.

1 Like
2

This tells me that the application sees the data but it can’t access it, likely due to incorrect permissions on the file. Another possiblity is an incomplete or corrupted download.

Start by verifying the permissions, ensure that the apps user can read the .zim in question.

For reference, I have kiwix-serve working just fine, but I added it as a custom YAML-app and I’ve made sure it has read access to the .zim’s I’ve added.

2 Likes
3

Yes, I agree with you but I don’t know, if the permission miss for /data or for /library and when it is /library then I need the full path and where I can find it.

I general the path would by /usr/local/bin/kiwix-serve but I can not access in truenas.

I setup Kiwix in yunohost without any problem for tests…but don’t like to work with 2 servers…

1 Like
4

I have no experience with the variant of Kiwix Server available in the TrueNAS apps market, but doesn’t that let you set up a host path volume when you’re installing/editing the app?

That’'s where you define where /data resides on your actual pool. The app then gets access to and mounts that directory inside the Docker container allowing Kiwix itself access to the contents.

However you have it setup your log files show Kiwix sees the Wikipedia .zim file but it can’t read it, so you need to go to directory on the host side, ideally using SSH or failing that using the built-in shell and check the permissions on the file.

1 Like
5

Did it with truenas app.

Changed the iX preconfigured setup to show /data to the local path with ZIM files and add app permission.

Thanks for your support.