Koha Installation on Ubuntu 24.04 LTS — A Complete Step-by-Step Guide

Four things, and the last one is the one people redo Apache for.

1. 1A server. Under about 20,000 items runs comfortably on 2 vCPU and 4 GB of RAM. A large or multi-branch library wants 4+ vCPU and 8–16 GB, more with Elasticsearch. Concurrent users decide this, not catalog size.
2. 2A current Ubuntu LTS or Debian stable, with sudo.
3. 3A UTF-8 locale. Koha requires one, and a mismatch produces character corruption in records that is miserable to unpick after cataloging has started.
4. 4Two hostnames, decided now — one for the public catalog, one for staff. They go into the config before the instance is created, and changing your mind afterwards means reconfiguring Apache.

$ sudo apt update && sudo apt -y upgrade$ sudo apt -y install wget gnupg lsb-release apt-transport-https ca-certificates$ sudo timedatectl set-timezone Etc/UTC

Set the timezone to your own — it decides when overdue notices are calculated and when the scheduled jobs run, so a wrong one is a support ticket six weeks later.

Use the community repository, not a distribution package — it is the one that is actually current.

$ wget -qO- https://debian.koha-community.org/koha/gpg.asc \    | sudo gpg --dearmor -o /usr/share/keyrings/koha-keyring.gpg$ echo "deb [signed-by=/usr/share/keyrings/koha-keyring.gpg] \https://debian.koha-community.org/koha stable main" \    | sudo tee /etc/apt/sources.list.d/koha.list$ sudo apt update

stable tracks the current stable series. Replace it with a release number (25.05) when a version has to be held.

$ sudo apt -y install mariadb-server$ sudo mysql_secure_installation

Do not create a database or user by hand. koha-create makes its own in step 7, and a hand-made one is a mismatch waiting to happen.

$ sudo apt -y install koha-common

This pulls in Apache, the Perl stack and the search indexer. It does not create a library yet — which is the step people believe they have already done.

$ sudo nano /etc/koha/koha-sites.conf

The file documents its own URL formula, and it is worth reading before editing:

OPAC:  http://<OPACPREFIX><instance><OPACSUFFIX><DOMAIN>:<OPACPORT>STAFF: http://<INTRAPREFIX><instance><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Set DOMAIN to your own, INTRAPORT to 8080 and OPACPORT to 80. The shipped defaults include INTRASUFFIX="-intra", ZEBRA_MARC_FORMAT="marc21", ZEBRA_LANGUAGE="en" and memcached enabled.

$ sudo a2enmod rewrite cgi headers proxy_http$ grep -q '^Listen 8080' /etc/apache2/ports.conf \    || echo "Listen 8080" | sudo tee -a /etc/apache2/ports.conf$ sudo systemctl restart apache2

The package ships its own Listen 8080, so the second command is usually a no-op — it is there because the one server where it is not is the one where the staff interface silently refuses to load.

$ sudo koha-create --create-db --marcflavor marc21 --zebralang en library

The instance name becomes database names, system users and file paths. Renaming it later is not practical, so pick something short and permanent — library rather than test2.

Flags worth knowing about now rather than later: --elasticsearch-server, --enable-sru, --letsencrypt, --smtp-host, --timezone and --defaultsql.

$ sudo koha-passwd library

Open the staff hostname on port 8080 and log in with that password. The installer then walks through schema creation and onboarding.

1. 1Confirm the database connection and create the schema.
2. 2Choose your MARC flavour — the same permanent choice as step 7.
3. 3Create the library, then the superlibrarian account you will actually use.
4. 4Add item types, patron categories and at least one circulation rule.

At this point Koha runs. It cannot yet send a notice, import a record from another catalog, charge a fine or survive a disk failure — which is what the rest of this guide is for.

$ sudo apt -y install certbot python3-certbot-apache$ sudo certbot --apache -d library.example.org -d library-intra.example.org$ sudo ufw allow 80,443/tcp$ sudo ufw enable

A staff login over plain HTTP is a credential leak. The staff interface also does not need to be reachable from the whole internet — restrict it to your institution's range if you can.

The most-skipped step on this page and the most consequential. koha-common installs the schedule for you — including a job that processes the message queue for every enabled instance every fifteen minutes.

$ koha-list --enabled$ systemctl list-timers | grep -i koha$ ls /etc/cron.d/koha-common /etc/cron.daily/koha-common

Koha 22.11 and later has Administration → SMTP servers in the staff interface; older versions edit koha-conf.xml. That is the easy half.

The half that gets marked done too early is DNS on your sending domain:

1. 1SPF — which servers may send as your domain.
2. 2DKIM — a signature proving the message was not altered.
3. 3DMARC — what a receiver should do when the first two fail.
4. 4A test to an address outside your institution — and check the spam folder, not just that Koha reported success.

Without those records, overdue notices land in spam and staff conclude the system is broken. It is the single most common Koha complaint and it is a DNS problem, not a Koha problem.

Without these, every record is typed by hand. With them a cataloger searches remote catalogs and imports a matching record in seconds — the difference between a week of cataloging and an afternoon.

The work is finding targets that are actually up and getting each one's connection and attribute settings right. A target with slightly wrong settings returns nothing at all rather than an error, which makes it tedious to debug and easy to give up on.

$ sudo koha-dump library$ sudo koha-dump --exclude-indexes library

koha-dump takes contents and configuration. --exclude-indexes produces a much smaller dump that is slower to restore, because Zebra has to rebuild.

$ systemctl status apache2 mariadb$ sudo koha-plack --status library$ koha-list --enabled

Then the checks a service restart cannot make for you: both URLs load over HTTPS, a test notice arrives at an external address, a Z39.50 search returns a record, and a checkout produces a due date.

Koha is packaged for Debian and Ubuntu, and those packages are what the community supports. There is no supported native Windows installation.

You can run it under WSL2 or in a virtual machine, and that is genuinely fine for evaluating Koha on your own laptop. It is a poor idea for a library that depends on it: you inherit a second layer to patch and a backup story that is harder to test. If Windows is a hard institutional requirement, run Ubuntu on a small server instead — or use a hosted catalog and skip the question.

Seven failures that account for most of them.

Each of these has an article of its own, with the full diagnosis: koha-conf.xml cannot be located, the web installer 500s or times out, Apache will not start, apt cannot install koha-common, 502 after enabling Plack, and reading the error log that has the real message.

The package install is step 4 of 16. A library that can actually open needs the configuration, the email and its DNS records, the notice templates, the copy-cataloging targets, the scheduled jobs and a backup that has been restored at least once.