Knowledge base
Koha, answered one question at a time
Short, practical answers for people running Koha — including the ones running it on their own server, who will never buy anything from us. Free, no sign-up, and every command verified against the Koha source rather than another blog.
Category
Installation & setup
Getting Koha onto a server, and the parts of the first day that are not the package install.
MySQL or MariaDB for Koha, and which version
Install MariaDB from your distribution's own repository. Both work — Koha depends on a virtual package that either satisfies — but one of them is what everybody else is running.
Verified against Koha 26.05
Koha packages or a source install: which one you want
Almost every library wants the packages. Here is exactly what a source install gives up — the koha-* commands, the upgrade path, and most published answers — and the two cases where it is still right.
Verified against Koha 26.05
Which Ubuntu or Debian version to install Koha on
The newest Ubuntu LTS or current Debian stable, and nothing else — here is the one command that confirms it before you build the server, and what each other choice actually costs.
Verified against Koha 26.05
apt cannot install koha-common
Unmet dependencies, NO_PUBKEY, or apt claiming the package does not exist. Four causes, in the order they actually occur, with the one command that tells you which of them you have.
Verified against Koha 26.05
Apache will not start: Invalid command 'RewriteEngine'
Apache refuses to start after enabling a Koha site because mod_rewrite is not enabled. One command fixes it — and the same class of error covers the other three modules Koha needs.
Verified against Koha 26.05
The Koha web installer returns a 500 error or times out
The installer dies partway through and the browser shows a 500 or a gateway timeout. Read the instance log to find out which step failed, then restart the install cleanly rather than retrying on a half-built database.
Verified against Koha 26.05
Koha cannot locate the configuration file koha-conf.xml
The error means the process has no KOHA_CONF set, not that the file is gone. Run the command through koha-shell, and here is how to confirm the file really is where Koha expects it.
Verified against Koha 26.05
Can you install Koha on Windows? (WSL2, VMs, and when not to)
There is no Windows build of Koha. You can run it on a Windows machine through WSL2 or a virtual machine — which is fine for evaluation and wrong for a live library.
Verified against Koha 26.05
Koha, Apache and port 8080: staff and OPAC on two hostnames
Koha serves two websites from one install. Here is how the OPAC and the staff interface are separated, why staff lands on port 8080, and how to move it off.
Verified against Koha 26.05
Finding your Koha instance’s admin password (koha-passwd)
The credentials the Koha web installer asks for are generated at install time and printed by koha-passwd. Here is how to find them, and how to reset a staff login.
Verified against Koha 26.05
Category
Configuration & operations
Email, scheduled jobs, backups, indexes — the things that fail silently rather than with an error.
Koha returns 502 or 503 after enabling Plack
Apache is proxying to Plack and cannot reach it. Nearly always two missing Apache modules — koha-plack tells you which, in a warning that scrolls past.
Verified against Koha 26.05
Koha internal server error: finding the line that caused it
A 500 page is Koha telling you nothing on purpose. The real message is in that instance's error log — here is which file to read, and the two causes that produce most of them.
Verified against Koha 26.05
Rebuilding the Zebra index when Koha search results go stale
A record you can open by its number but cannot find by searching means the index is behind, not that the record is missing. Here is how to rebuild it properly.
Verified against Koha 26.05
Backing up Koha with koha-dump — and restoring it
A package install already backs itself up nightly, keeps two days, and writes to a disk that dies with the server. Here is how to check it, and how to restore.
Verified against Koha 26.05
Koha cron jobs: which ones matter, and what breaks silently without each
A package install schedules about fifteen jobs. This is what each one does, when it runs, and the exact symptom a library sees when it stops.
Verified against Koha 26.05
Using a Gmail account as Koha’s SMTP server
Gmail works as Koha’s mail server, but only with an app password and two-step verification on. Here are the exact settings, and the limits worth knowing before you rely on it.
Verified against Koha 26.05
How to configure SMTP in Koha so notices actually send
Koha queues every notice and a cron job delivers them. Configure the SMTP server, turn email on for the instance, and check the queue — in that order.
Verified against Koha 26.05
Category
Cataloging & MARC
Records in, records out, and the copy-cataloging targets that save typing them by hand.
MARC21 or UNIMARC: the choice you cannot undo
Koha asks for a MARC flavour before you catalogue anything, and changing it later means re-importing the catalogue. Unless you have a specific reason, choose MARC21.
Verified against Koha 26.05
Adding a Z39.50 target to Koha for copy cataloging
Add a remote catalog once and your catalogers stop typing records by hand. Here are the settings, a target that definitely works, and why a search returns nothing.
Verified against Koha 26.05
Category
OPAC & customization
Changing how the public catalog looks, and where to make the change so an upgrade cannot undo it.
Changing the Koha OPAC header, footer and navigation
The header, footer and side navigation are content, not code. They are edited in Tools → HTML customizations — one region per named location.
Verified against Koha 26.05
OPACUserCSS and OPACUserJS: what belongs in each
Two system preferences hold your OPAC’s custom CSS and JavaScript. Here is what goes in each, what does not belong in either, and how to keep it upgrade-proof.
Verified against Koha 26.05
Longer reads
When one answer is not enough
The installation guide walks a whole first day end to end, and the blog argues the decisions behind it.