10 guides
Koha Installation Guides and Fixes
Install Koha without guesswork: supported systems, package errors, Apache and ports, first-login problems and the steps after 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