Koha on Debian

== Before you begin ==
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
sudo 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.
==== 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.11 (LTS) (stable) is the current stable release and the next long-term support release
* 24.05 (oldstable) follows one release behind the current stable release
* 23.11 (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.11 release: 
echo 'deb [signed-by=/etc/apt/keyrings/koha.asc] https://debian.koha-community.org/koha 24.11 main' | sudo tee /etc/apt/sources.list.d/koha.list
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 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 25.05 release becomes available: 
* if you follow the current stable release, you would automatically be upgraded from Koha 24.11 to 25.05 when the 25.05 release becomes available
* if you follow oldstable, you would automatically be upgraded from Koha 24.05 to 24.11.
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 (currently 24.11 LTS) is the latest stable release and next long-term support release
*oldstable (currently 24.05) follows one release behind the current stable release
* oldoldstable (currently 23.11) follows two releases behind the current stable release
* oldoldoldstable (currently 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: 
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 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 ===
 $ 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 catalog 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 cgi headers proxy_http
 $ 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 ====
If you are running your database locally (replace libraryname with the name of your library): 
 $ sudo koha-create --create-db libraryname
 $ sudo koha-plack --enable libraryname
 $ sudo koha-plack --start libraryname
 $ sudo systemctl restart apache2
For more options, see Commands provided by the Debian packages#koha-create.Important: Make sure to check available options of koha-create 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: 
# Remove /etc/mysql/koha-common.cnf
# 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
# Read the man pages for koha-create, paying attention to the information on --request-db and --populate-db.
# Using --request-db will disable koha instance, so to enable the instance after using --populate-db, perform command koha-enable libraryname.
=== Access the web interface ===
You will need to have your DNS set up for this. The default hostnames are:
* libraryname.myDNSname.org for the public interface 
* libraryname-intra.myDNSname.org for the staff interface
where libraryname is the name provided to koha-create.
In the default configuration it is impossible to access the web interfaces directly by the server's IP address, so you will have to change the above hostnames by editing /etc/apache2/sites-enabled/libraryname.conf and reloading Apache. Alternatively, you may temporarily modify hosts file on your client machine to have to temporarily point these hostnames to the server's IP address.
Open a web browser, and point it to your staff interface, by going to http://libraryname-intra.myDNSname.org, or whatever you manually configured. 
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
Outputs:
Username for temp: koha_libraryname
Password for temp: randompasswordtext
Press enter to clear the screen...
Or you can access them for shell scripting directly from the generated config file:
 # KOHA_USER=$(xmlstarlet sel -t -v '/yazgfs/config/user' /etc/koha/sites/libraryname/koha-conf.xml)
 # KOHA_PASS=$(xmlstarlet sel -t -v '/yazgfs/config/pass' /etc/koha/sites/libraryname/koha-conf.xml)
Note that these credentials are only used for the web installer, which will prompt you at the end to provide new actual username and password for the first administrative user.
==== 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. Avoid using extra reverse proxies in front of the server during the installation.
== 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 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
The installed Koha languages will be auto-updated as the language packages get updated by APT.
Please note that you should also have the relevant locales installed on the base Debian system to avoid running into some issues. Edit the file /etc/locale.gen and uncomment the UTF-8 entries for respective languages, then run locale-gen command.
If you don't do the above, you will likely experience warnings in logs, with practical effects like the page titles (<title>) not being translated. Note that many of the Debian slim/cloud default installs will only have "C" locale enabled by default, with not even the "en_US" one being enabled.
=== 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 configured and enabled Koha services, such as Plack daemon, Zebra daemon, Z39.50 responder daemon, SIP daemon are running. A systemd unit koha-common is also installed. You can use the start, stop, and restart commands to control these.
=== MySQL vs MariaDB ===
MariaDB is now the default mysql server in Debian, therefore we recommend using Koha with MariaDB over MySQL.
=== 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
Start up the server:
 $ sudo systemctl daemon-reload
 $ sudo systemctl enable --now elasticsearch.service
Install the analysis-icu plugin:
 $ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
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.
Since Elasticsearch 8.0, security features are enabled and unauthenticated users cannot connect to the service. Either read the password for elastic user from the output of apt install command above, or reset it with:
 $ sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Afterwards, edit /etc/koha/sites/libraryname/koha-conf.xml and find the section <elasticsearch>. Inside of it you should have the below snippet if you installed Koha recently (otherwise, add it):
 <!-- If you are using authentication, you will also need to use HTTPS. Uncomment and tweak the following for your ES setup. -->
 <!-- NOTE: instead of userinfo, you can alternatively provide the username and password in URL in the server element -->
 <!--
 <userinfo>elastic:CHANGEME</userinfo>
 <use_https>1</use_https>
 -->
Change CHANGEME to the password of the elastic user that you have generated above and remove the <!-- and --> around the values.
NOTE: On older Koha versions 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. Disabling security is not recommended if it can be avoided!
Restart the services to have them pick up the changes:
 $ sudo systemctl restart elasticsearch.service
 $ sudo systemctl restart koha-common.service
Wait a few seconds, then check if it is running correctly.
With security enabled, run:
 $ curl -k -u 'elastic:CHANGEME' https://localhost:9200
With security disabled, run:
 $ curl localhost:9200
Expected output similar to:
{
 "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
To make sure it's working, search in your catalogue for * (asterisk symbol). If you get any results, assuming non-empty catalog, it's working (in Zebra the asterisk would not work).
=== OpenSearch ===
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"
 $ mv /usr/sbin/anacron /usr/sbin/anacron-temporarily-renamed
== Upgrading Koha ==
Before upgrading Koha, update your system's package information:
 $ sudo apt 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 (by setting it to follow specific version releases as recommended), an upgrade should be as easy as this:
 $ sudo apt 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. If you use Elasticsearch and it's being updated, remember to reinstall the analysis-icu plugin as outlined in Elasticsearch installation section above.
=== 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 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 update
 $ apt-cache policy koha-common | grep -E 'Installed|Candidate'
 Installed: 19.05.14-1
 Candidate: 21.05.04-1
If the 'Candidate' version looks correct, then:
 $ sudo apt 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 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 ===
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
==== Elasticsearch: Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding] ====
Reinstall analysis-icu plugin (you need to do this after every Elasticsearch update, remember!):
 $ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin remove analysis-icu
 $ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
 $ sudo systemctl restart elasticsearch.service
==== Elasticsearch exited unexpectedly, with exit code 137 ====
You probably don't have enough memory for what ES expects by default. Create a file under /etc/elasticsearch/jvm.options.d and add to it something like -Xms512m -Xms512m. Search the internet for more information.
 
Category:Documentation Category:Installation Category:Debian_Packages Category:Installation_alternatives