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.
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 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.