Koha on Debian

From Koha Wiki
(Redirected from Debian)
Jump to navigation Jump to search

Before you begin

These instructions assume you are starting from scratch, on a fresh server, with none of the prerequisites already installed. Koha is big, and it is built on top of a stack of other software that is also big. 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 MySQL server on the same machine as Koha, assume it is going to need another 350MB - 500MB of RAM.

Note that there are many opportunities to tune the configurations of MySQL and Koha to reduce their memory consumption, but those optimizations and their consequences are outside of the scope of this document. Additionally, having swap enabled will help absorb any spikes in memory needs due to activity. (4GB minimum swap file/partition)

Debian packages on Koha

The Debian packages are the preferred, and easiest, way to install Koha on Debian based operating systems, including Ubuntu and Mint. 64bit OS systems are recommended, as 32bit systems are not currently tested.

See the system requirements and recommendations page to know which Os versions are tested and known as working.

Note: Debian 8 (Jessie) reached end of life in June 2020, as such Koha support for it ended with 18.11.18, 19.05.12, 19.11.06 and 20.05.00.

Installation process

Commands that are in a box and start with '$' 

$ like this

are intended to be run at the command line of your server (but don't include the '$'.)

Set up package sources

Add the GPG key to your system so that you know that the packages haven't been tampered with: 

$ sudo apt update
$ sudo apt -y install sudo wget gnupg
$ wget -q -O- https://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
$ sudo apt update

The apt-key deprecation warning

Since apt-key is deprecated and will no longer be available in future releases of Debian and Ubuntu there's a new way of adding GPG-keys. While apt-key will tell you to manage keys under /etc/trusted.gpg.d the Debian community recommends a different approach. Read this for reference: https://wiki.debian.org/DebianRepository/UseThirdParty 

$ sudo apt update
$ sudo apt -y install sudo wget gnupg2
$ wget -qO - https://debian.koha-community.org/koha/gpg.asc | sudo gpg --dearmor -o /usr/share/keyrings/koha-keyring.gpg
$ sudo apt update

This means that instead of the regular entry in /etc/apt/sources.list.d/koha.list which looks like this: 

 deb https://debian.koha-community.org/koha stable main

You'll need to specify the location of the key-file inside this entry like this: 

 deb [signed-by=/usr/share/keyrings/koha-keyring.gpg] https://debian.koha-community.org/koha stable main

Pick which Koha release to follow (codename or suite)

Pick what version of Koha you want. You can either follow by codename (version number), or by suite.

Follow a Koha release 'suite'

If you follow a Koha release suite, you will automatically upgrade to the next Koha release series at the start of every 6 month release cycle.

Suites available this release cycle are:

  • stable (23.05) is the current stable release
  • oldstable (22.11) follows one release behind the current stable release
  • oldoldstable (22.05) follows two releases behind the current stable release

If you chose oldstable suite: 

$ echo 'deb https://debian.koha-community.org/koha oldstable main' | sudo tee /etc/apt/sources.list.d/koha.list

If you chose stable suite: 

$ echo 'deb https://debian.koha-community.org/koha stable main' | sudo tee /etc/apt/sources.list.d/koha.list

Update the package list: 

$ sudo apt update

Follow a Koha release 'codename'

Or, if you follow a codename (version number), you will stay on that branch until you change your apt configuration to follow another.

Example: Release of 20.05

If you have set "20.05" in your apt configuration, you will stay on 20.05 until you update your apt configuration to follow a newer version

(this is recommended for production systems, so you don't 'accidentally' upgrade to a new major release)


Koha codenames (version numbers) activity maintained during this release cycle (23.05) are:

  • 23.05 is the current stable release
  • 22.11 follows one release behind the current stable release
  • 22.05 follows two releases behind the current stable release
  • 21.11 follows three releases behind the current stable release

If you chose 22.05: 

$ echo 'deb https://debian.koha-community.org/koha 22.05 main' | sudo tee /etc/apt/sources.list.d/koha.list

Or, If you chose 21.11: 

$ echo 'deb https://debian.koha-community.org/koha 21.11 main' | sudo tee /etc/apt/sources.list.d/koha.list

Update the package list: 

$ sudo apt-get update

No new Debian packages will be released for the following Koha versions. Please upgrade to a newer version of Koha.

  • 16.05 - the last version available from the repository is 16.05.19.
  • 16.11 - the last version available from the repository is 16.11.16.
  • 17.05 - the last version available from the repository is 17.05.14.
  • 17.11 - the last version available from the repository is 17.11.18.
  • 18.05 - the last version available from the repository is 18.05.14.
  • 18.11 - the last version available from the repository is 18.11.17.
  • 19.05 - the last version available from the repository is 19.05.17.
  • 19.11 - the last version available from the repository is 19.11.29.
  • 20.05 - the last version available from the repository is 20.05.18.
  • 20.11 - the last version available from the repository is 20.11.19.

Support for Koha on older versions of Debian/Ubuntu

Older versions of Debian/Ubuntu currently supported are:

  • Ubuntu 18.04/Bionic

If you are unsure of your Debian/Ubuntu codename, run the following 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

Install Koha

$ sudo apt install koha-common

Install the database

You can either install MariaDB (recommended). 

$ sudo apt install mariadb-server

Or you can install MySQL server. 

$ sudo apt install mysql-server

You should then take a look at the DBMS_configuration page if you are using a version of Koha released before 18.05.00, 17.11.05 or 17.05.11

Configure the defaults

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

Only do this if you are running MySQL 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 are a UNIMARC user, you'll need to use the --marcflavor option to set your instance up with the correct indexing configuration for this MARC flavour.

If you are running MySQL on another server:

  • remove /etc/mysql/koha-common.cnf
  • create a new "option file" in its place with the same filename 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.

Setup plack

You will need set an Apache module for koha-plack works: 

$ sudo a2enmod headers proxy_http

then: 

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

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.

Further configuration

E-mail

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

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 and MariaDB

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 and the Java JDK 

$ sudo apt install koha-elasticsearch openjdk-11-jdk-headless

Download the Elasticsearch server (v6 is known to work, v7 is ready for Koha 22.11) 

$ sudo apt-get install apt-transport-https
$ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/6.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-6.x.list
$ sudo apt-get update && sudo apt-get install elasticsearch

Install the analysis-icu plugin 

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

Restart the server 

$ sudo service elasticsearch restart

Wait a few seconds then check if it is running correctly 

$ curl localhost:9200
{
   "name" : "MLhu8oD",
   "cluster_name" : "elasticsearch",
   "cluster_uuid" : "cTXuxxIPTd2KrWgyRCPAxw",
   "version" : {
     "number" : "6.8.23",
     "build_flavor" : "default",
     "build_type" : "deb",
     "build_hash" : "4f67856",
     "build_date" : "2022-01-06T21:30:50.087716Z",
     "build_snapshot" : false,
     "lucene_version" : "7.7.3",
     "minimum_wire_compatibility_version" : "5.6.0",
     "minimum_index_compatibility_version" : "5.0.0"
   },
   "tagline" : "You Know, for Search"
}

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

$ koha-elasticsearch --rebuild -d libraryname

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-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 "Pick which Koha version to follow" 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'
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

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

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

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_on_Debian&oldid=33604"