Koha on Debian

Search Koha Wiki

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Contents [hide]
1 Before you begin
2 Conventions
3 Installing the operating system
4 Using the Koha packages
4.1 Setting up package sources
4.2 Choosing what Koha release to follow - a version number or a codename
4.2.1 Following a version number (recommended)
4.2.2 Following a codename (not recommended)
4.2.3 NOT UP TO DATE - Support for Koha on older versions of Debian or Ubuntu

5 Installing Koha
5.1 Install Koha
5.2 Install the database
5.3 Configure the defaults for Koha instances
5.4 Set up Apache
5.5 Create a Koha instance
5.5.1 Using a local database
5.5.2 Using a database on another server TO BE TESTED AND UPDATED IF REQUIRED

5.6 Set up plack

5.7 Access the web interface
5.7.1 If you encounter timeout errors

6 Additional configuration
6.1 Email
6.2 Translations TO BE UDPATED
6.3 Searching and non-latin languages
6.4 List of commands provided by the Debian packages
6.5 Services
6.6 MySQL vs MariaDB TO BE UDPATED
6.7 Elasticsearch
6.8 Open Search
6.9 Anacron

7 Upgrading Koha
7.1 Upgrading Koha to a major version

8 Koha packaging information

8.1 Release policy
8.2 How koha-create configures your system
8.3 Packaging releases
8.4 Other things

9 Warnings and errors

9.1 Failed to enable unit: Unit /run/systemd/generator.late/koha-common.service
9.2 Errors were encountered while processing: libapache2-mpm-itk

Before you begin

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
These instructions assume you are starting from scratch, on a fresh server, with none of the prerequisites already
installed.

Koha is large, and it is built on top of a stack of other software (such as Perl, Perl packages from CPAN, MySQL or
MariaDB for the database, Apache for the webserver, Zebra or Elasticsearch/Open Search for the search engine).
As a result, the memory requirements to run it are going to be significant (2GB minimum).

You must ensure that the target machine has adequate free memory available to run Koha before you begin.

Following these instructions will result in an instance of Koha and the necessary support software which together
consume between 750MB - 1GB of memory at idle. If you are installing the database server on the same machine
as Koha, assume it is going to need another 350MB - 500MB of RAM.

Note that the database and webserver can be tuned to reduce memory consumption, but those optimizations and
their consequences are outside of the scope of these instructions. Additionally, having swap enabled will help
absorb any spikes in memory needs (4GB minimum swap file/partition).

Conventions
Commands that are in a box and start with '$' are intended to be run at the command line of your server (don't
include the '$'):

$ enter a command

Installing the operating system

Debian based operating systems are recommended. This includes Debian, Ubuntu, and Mint.

Normally, you would install a minimal server version of the operating system, and then use the available Koha
packages.

See the system requirements and recommendations page for information about which operating system
versions are tested and known to work.

Using the Koha packages

Koha's Debian packages are the preferred, easiest, and recommended way to install Koha.

Setting up package sources

$ sudo apt update

$ sudo apt install sudo apt-transport-https ca-certificates curl
$ sudo mkdir -p --mode=0755 /etc/apt/keyrings
$ curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o
/etc/apt/keyrings/koha.asc
$ sudo apt update

Choosing what Koha release to follow - a version number or a codename

You can choose to follow a specific Koha version number or a codename for the release. This determines what
packages are updated when you run updates.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Following a version number (recommended)

When you follow a specific Koha version number, you stay on that version of Koha until the package sources are
changed. This is recommended for production environments, so that you don't 'accidentally' upgrade to a new
major release. When you run updates, you will only upgrade to the latest maintenance release for the version
chosen.

The current Koha version numbers and their codenames are:

24.05 (stable) is the current stable release

23.11 (oldstable) follows one release behind the current stable release
23.05 (oldoldstable) follows two releases behind the current stable release
22.11 (LTS) (oldoldoldstable) is the long-term support release, maintained for approximately 3 1/2 years

To update your package source list to use the 24.05 release:

$ echo 'deb [signed-by=/etc/apt/keyrings/koha.asc] https://debian.koha-

community.org/koha 24.05 main' | sudo tee /etc/apt/sources.list.d/koha.list

To update your package source list to use the 23.11 release:

$ echo 'deb [signed-by=/etc/apt/keyrings/koha.asc] https://debian.koha-

community.org/koha 23.11 main' | sudo tee /etc/apt/sources.list.d/koha.list

To update the packages list:

$ sudo apt update

Following a codename (not recommended)

When you follow a codename for a release, you are automatically upgraded to the next major Koha release at the
start of every six month release cycle. For example when the 24.11 release becomes available: if you follow the
current stable release, you would automatically be upgraded from Koha 24.05 to 24.11 when the 24.11 release
becomes available; if you follow oldstable, you would automatically be upgraded from Koha 23.11 to 24.05.

Following a codename for a release is NOT recommended for a production environment, unless you like "living on
the edge". Major releases contain new features and many enhancements, and sometimes unexpected issues can
occur despite a release teams best efforts to create a stable release. It is highly recommended that libraries test
before upgrading between major versions. See Koha versioning and the recommendations section.

The current codenames and their versions are:

stable (24.05) is the latest stable release

oldstable (23.11) follows one release behind the current stable release
oldoldstable (23.05) follows two releases behind the current stable release
oldoldoldstable (22.11) (LTS) is the long-term support release, maintained for approximately 3 1/2 years

To update the package source list to use the stable release:

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 $ echo 'deb [signed-by=/etc/apt/keyrings/koha.asc] https://debian.koha-
community.org/koha stable main' | sudo tee /etc/apt/sources.list.d/koha.list

To update the package source list to use the oldstable release:

$ echo 'deb [signed-by=/etc/apt/keyrings/koha.asc] https://debian.koha-

community.org/koha oldstable main' | sudo tee /etc/apt/sources.list.d/koha.list

To update the packages:

$ sudo apt update

NOT UP TO DATE - Support for Koha on older versions of Debian or Ubuntu

Older versions of Debian/Ubuntu currently supported are:

Ubuntu 18.04/Bionic

If you are unsure of your Debian or Ubuntu codename, run these commands:

$ sudo apt-get -y install lsb-release

$ lsb_release -cs
bionic

Below are some examples, remember to replace both Koha and Debian/Ubuntu codenames with your required
values

If you choose Koha 21.05 and Debian/Ubuntu codename bionic

$ echo 'deb http://debian.koha-community.org/koha 21.05 main bionic' | sudo tee

/etc/apt/sources.list.d/koha.list

or, if you choose Koha stable and Debian/Ubuntu codename bionic

$ echo 'deb http://debian.koha-community.org/koha stable main bionic' | sudo

tee /etc/apt/sources.list.d/koha.list

Then update the package database:

$ sudo apt update

Installing Koha
Install Koha

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 $ sudo apt install koha-common

Install the database

You can use either MariaDB (recommended) or MySQL as the database server.

This is not required if you are using a database on another server.

To use MariaDB:

$ sudo apt install mariadb-server

To use MySQL:

$ sudo apt install mysql-server

Configure the defaults for Koha instances

Edit the file /etc/koha/koha-sites.conf and adjust it to suit the configuration that you'd like.

Set the DOMAIN value to the domain you wish to access this Koha from. Also pay attention to the INTRASUFFIX
as your DNS entries will also require this. Instructions for setting up a domain for Koha can be found on the page
How to set up a domain name for Koha.

If your catalogue is not MARC21, change ZEBRA_MARC_FORMAT. You may also adapt ZEBRA_LANGUAGE.

Some more useful information on how to set up your koha-sites.conf can also be found in Appendix A: Named-
based vs. IP-based installations.

Set up Apache

$ sudo a2enmod rewrite

$ sudo a2enmod cgi
$ sudo systemctl restart apache2

If you are configuring Koha for access by IP address rather than by domain name, please remember to edit
/etc/apache2/ports.conf and make sure the following lines are present:

Listen 80
Listen <staff interface port number>

You will only need the second Listen entry, if you have chosen to make the staff interface accessible on a different
port.

Create a Koha instance

Using a local database

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
If you are running your database locally (replace libraryname with the name of your library):

$ sudo koha-create --create-db libraryname

For more options, see Commands provided by the Debian packages#koha-create.

Important: Make sure to check available options carefully. If you use UNIMARC, you'll need to use
the --marcflavor option to set your instance up correctly.

Using a database on another server TO BE TESTED AND UPDATED IF REQUIRED

If you are running your database on another server:

1. Remove /etc/mysql/koha-common.cnf
2. Create a new "option file" in its place with the same file name containing the client connection information
for the server (the same syntax you'll find in a my.cnf file).
You will need to specify the host, user, and password within a [client] option group.
Koha commands will automatically use the /etc/mysql/koha-common.cnf via the --defaults-extra-file
option for the MySQL CLI client

3. Read the man pages for koha-create, paying attention to the information on --request-db and --
populate-db.
4. Using --request-db will disable koha instance, so to enable the instance after using --populate-db,
perform command koha-enable.

Set up plack
You will need set up Apache modules for koha-plack to work:

$ sudo a2enmod headers proxy_http

$ sudo koha-plack --enable libraryname
$ sudo koha-plack --start libraryname
$ sudo systemctl restart apache2

Access the web interface

You will need to have your DNS set up for this. The default hostnames are:

libraryname.domain for the public interface

libraryname-intra.domain for the staff interface

where:

libraryname is the name provided to koha-create

domain is the value of DOMAIN that you set in /etc/koha/koha-sites.conf

If you want to change the hostname details of the instance, you can edit /etc/apache2/sites-
enabled/libraryname.conf and restart Apache.

Open a web browser, and point it to your staff interface, by going to http://libraryname-intra.domain, or
whatever you manually configured.

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
When you see the login for the Koha installer, the username and password are in the koha-conf.xml file for the
instance.

You can view the password with:

$ sudo koha-passwd libraryname

The default username is koha_libraryname

Or you can view them with:

$ sudo xmlstarlet sel -t -v '/yazgfs/config/user'

/etc/koha/sites/libraryname/koha-conf.xml
koha_libraryname
$ sudo xmlstarlet sel -t -v '/yazgfs/config/pass'
/etc/koha/sites/libraryname/koha-conf.xml
randompasswordtext

If you encounter timeout errors

Some steps taken by the web-based installer to set up database tables may take considerable time to complete,
and may generate timeout errors. If you receive a "Gateway Timeout" error in the web browser, try editing the file
/etc/apache2/apache2.conf to increase apache's Timeout setting.

Additional configuration
Email
By default, email is turned off. This is to let you get everything set up before you risk sending unwanted notices to
people. To turn email on:

$ sudo koha-email-enable libraryname

Translations TO BE UDPATED
To see all the language codes:

$ sudo koha-translate --list --available

am-Ethi
ar-Arab
as-IN
...

Translations can be installed as required:

$ sudo koha-translate --install am-Ethi ar-Arab as-IN

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Searching and non-latin languages
To get searching with non-latin languages (such as Russian, Chinese and Arabic) working correctly in Koha you
need to setup and configure ICU.

List of commands provided by the Debian packages

There is a list of Commands provided by the Debian packages. All commands begin with koha-, and have man
pages installed, for example:

$ man koha-create

Services
Koha installs a service in /etc/init.d/koha-common. This ensures that the zebra daemon and, if configured,
SIP daemon are running. You can use the start, stop, and restart commands to control these.

MySQL vs MariaDB TO BE UDPATED

MariaDB 10.1 is now the default mysql server in Debian 9 "Stretch", therefore we recommend using Koha with
MariaDB over MySQL.

An upgrade guide from MySQL to MariaDB exists here

Due to how MySQL behaves with AUTO_INCREMENT values you should take a look at this dedicated wiki page
to fix potential issues.

Elasticsearch
If you want to use Elasticsearch instead of Zebra, please follow these steps:

Install the Koha dependencies:

$ sudo apt install koha-elasticsearch

Download the Elasticsearch server:

$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o

/etc/apt/keyrings/elasticsearch.asc
$ echo "deb [signed-by=/etc/apt/keyrings/elasticsearch.asc]
https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee
/etc/apt/sources.list.d/elasticsearch.list
$ sudo apt update && sudo apt install elasticsearch

Install the analysis-icu plugin:

$ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Note that you need to manually remove and re-install the analysis-icu plugin after every Elasticsearch package
update (using the elasticsearch-plugin tool above), which is a hassle.

Restart the server:

$ sudo systemctl restart elasticsearch

Wait a few seconds, then check if it is running correctly.

NOTE: On newer versions of Elasticsearch you may need to disable the security features in order to allow the
HTTP API port to work. If you do that, ensure that you configure it to NOT be accessible from the open internet (for
example with a firewall like ufw), only from within localhost. If the command below fails, it's not set up properly and
won't work in Koha.

$ curl localhost:9200
{
"name" : "koha",
"cluster_name" : "elasticsearch",
"cluster_uuid" : "cTXuxxIPTd2KrWgyRCPAxw",
"version" : {
"number" : "8.15.0",
"build_flavor" : "default",
"build_type" : "deb",
"build_hash" : "1a77947f34deddb41af25e6f0ddb8e830159c179",
"build_date" : "2024-08-05T10:05:34.233336849Z",
"build_snapshot" : false,
"lucene_version" : "9.11.1",
"minimum_wire_compatibility_version" : "7.17.0",
"minimum_index_compatibility_version" : "7.0.0"
},
"tagline" : "You Know, for Search"
}

Switch the system preferences SearchEngine to 'Elasticsearch' then index your records.

$ koha-elasticsearch --rebuild -d libraryname

Open Search
To be added

Anacron
Zebra server may go down occasionally if you are using Anacron (see
https://lists.katipo.co.nz/pipermail/koha/2016-September/046167.html ).

To avoid that:

1. Edit /etc/cron.d/anacron and add a # to turn off the line starting with 30 7 * * * ....anacron...

2. Rename "anacron"

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 $ mv /usr/sbin/anacron /usr/sbin/anacron-temporarily-renamed

Upgrading Koha
Before upgrading Koha, update your system's package information:

$ sudo apt-get update

To confirm which version of Koha is installed, and which version will be upgraded to, run:

$ apt-cache policy koha-common | grep -E 'Installed|Candidate'

Installed: 21.05.01-1
Candidate: 21.05.09-1

If you installed Koha as described above, an upgrade should be as easy as this:

$ sudo apt-get upgrade

This will upgrade to the latest minor version, e.g. from 19.11.10 til 19.11.13. (It will also upgrade all the other
software on your server that needs an upgrade.)

The upgrade will print a list of software to be updated, please read this list before proceeding with the upgrade,
and if packages related to mysql or mariadb are present, you should cancel and run the database upgrade first. If
the package listed was mariadb-server*, first run:

$ sudo apt-get install mariadb-server

And when it is done continue with:

$ sudo apt-get upgrade

This will prevent a problem where koha's database upgrade tries to run while the database server is being
updated.

Upgrading Koha to a major version

If you want to upgrade to a newer major version (e.g. from 19.11.x to 20.05.x) you may need to adjust the
file /etc/apt/sources.list.d/koha.list before you do "sudo apt-get update". See "Choosing what Koha release
to follow - a version number or a codename" above for an idea of what you need to do.

Then, after adjusting /etc/apt/sources.list.d/koha.list you should be able to upgrade with the same commands:

$ sudo apt-get update

$ apt-cache policy koha-common | grep -E 'Installed|Candidate'

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
 Installed: 19.05.14-1
Candidate: 21.05.04-1

If the 'Candidate' version looks correct, then:

$ sudo apt-get upgrade

Sometimes this will not upgrade Koha, because it is "held back" (this happens when the upgrade means you have
to install new packages on the server, e.g. new Perl modules). In that case you have to try again with this
command:

$ sudo apt-get dist-upgrade

Remember to always scan the output of these commands for any error messages related to the upgrading of the
Koha database.

Confirm the 'koha-common' package has been installed successfully

$ dpkg -s koha-common | grep Status

Status: install ok installed

Koha packaging information

Release policy
All release series aim to release a new Koha version around the 20th of every month.

How koha-create configures your system

When you create an instance with koha-create, a few things happen. For the sake of example, this assumes
that the instance you created is called library.

A system user is created, called library-koha. All things to do with this instance will be run as this user.
(If you have a local MySQL) a new MySQL user is created called koha_library
(If you have a local MySQL) a new MySQL database is created called koha_library
/var/lib/koha/library is created and populated with a default directory structure.
The Koha sites directory (/etc/koha/sites/library) is created and populated. In particular, a koha-
conf.xml is generated and put there with the passwords that were randomly generated for the database and
zebra.
An apache configuration file is put in /etc/apache2/sites-available/library.conf. Apache is
restarted to make the change take effect.
A Zebra daemon for this instance is started, running as the library-koha system user.

Packaging releases

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
There is a bit of a mind-dump of information on Building Debian Packages for release. If you want to maintain your
own packages, also have a look at Building Debian Packages - The Easy Way.

Other things
Using the Index Daemon with the packages
Newbie guide - to begin the working configuration
Building Debian Dependencies - what to do if we need to add a new dependency that's not in Debian

Warnings and errors

Failed to enable unit: Unit /run/systemd/generator.late/koha-common.service

You can safely ignore the following warning when installing or upgrading koha, (fixed in bug 33371 )

Failed to enable unit: Unit /run/systemd/generator.late/koha-common.service is

transient or generated.

Errors were encountered while processing: libapache2-mpm-itk

If you see this:

Errors were encountered while processing:

libapache2-mpm-itk
apache2-mpm-itk
koha-common

Then do this:

$ sudo a2dismod mpm_event

$ sudo apt-get install -f

Developer handbook

Getting involved | Development workflow | Bug Reporting Guidelines | RFCs | Plugins | Plugin hooks
Version Control Using Git | git bz | Commit messages | Sign off on patches | QA Test Tools | How to QA |
Debugging in VIM
Coding Guidelines | Koha Objects | Rest Api HowTo | Coding Guidelines - API | Unit Tests | Continuous
Integration | Interface patterns | Database updates | Adding a syspref | Bootstrap and LESS
Debian Packages | Building Debian Packages | Easy Package Building | Commands
External: Dashboard | Bugzilla | Schema | perldoc | REST API | Jenkins

Categories: Documentation Installation Debian Packages Installation alternatives

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF
Home > Documentation
Home > Documentation > Installation
Home > Documentation > Installation > Debian Packages
Home > Documentation > Installation > Installation alternatives
Koha > Technical > Administration
Koha > Technical > Administration
Koha > Technical > Administration

Explore our developer-friendly HTML to PDF API Printed using PDFCrowd HTML to PDF