Koha on Debian

From Koha Wiki

(Redirected from Koha 3.x on Debian Squeeze)
Jump to: navigation, search
Home > Documentation
Home > Documentation > Installation
Home > Documentation > Installation > Debian Packages
Home > Documentation > Installation > Installation alternatives
Koha > Technical > Administration
Koha > Technical > Administration
Koha > Technical > Administration

Contents

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.

OS versions tested as working:

  • Debian 10 (Buster)
  • Debian 9 (Stretch)
  • Debian 8 LTS (Jessie) [1]
  • Ubuntu 20.04 (Focal)
  • Ubuntu 18.04 LTS (Bionic) [1]
  • Ubuntu 16.04 LTS (Xenial) [1]

[1] See section 'Support for Koha on older versions of Debian/Ubuntu'

Note: Debian 8 (Jessie) reaches end of life in June 2020, as such Koha support for it will end 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:

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

Pick which Koha version to follow

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

Follow a suite: stable, oldstable …

If you follow a suite, you will automatically upgrade to a newer branch each release cycle.

Suites available this release cycle are

  • stable (20.05) is the current stable release
  • oldstable (19.11) follows one release behind the current stable release
  • oldoldstable (19.05) follows two releases behind the current stable release
  • unstable (master) follows the current development, this is intended for developers and testers only

If you chose oldstable:

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

If you chose stable:

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

Update the package list:

$ sudo apt-get update

Follow a codename (version number): 20.05, 19.11, 19.05

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 "19.05" in your apt configuration, you will stay on 19.05 until you change your apt configuration to follow 19.11.

Codenames (version numbers) available this release cycle are:

  • 19.05 follows two releases behind the current stable release
  • 19.11 follows one release behind the current stable release
  • 20.05 is the current stable release
  • dev (master) follows the current development, this is intended for developers and testers only

If you chose 20.05:

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

If you chose 19.11:

$ echo 'deb http://debian.koha-community.org/koha 19.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.

Support for Koha on older versions of Debian/Ubuntu (Debian 8, Ubuntu 18.04, Ubuntu 16.04)

If you are unsure of your Debian/Ubuntu codename, run the following command

$ lsb_release -sc

If you choose Koha 20.05 and Debian/Ubuntu codename jessie

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

Update the package list:

$ sudo apt-get update

Install Koha

$ sudo apt-get install koha-common

Aside: a common problem on Ubuntu happens here

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

And everything will fix itself up.

Install the database

You can either install MariaDB.

$ sudo apt-get install mariadb-server

Or you can install MySQL server.

$ sudo apt-get 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.

Set up Apache

$ sudo a2enmod rewrite 
$ sudo a2enmod cgi 
$ sudo service apache2 restart

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 8080

(assuming you want your OPAC to be accessible on port 80 and your staff client on port 8080)

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.

If you are running MySQL on another server:

  • remove /etc/mysql/koha-common.cnf
  • create a new file in its place containing the connection information for the server, in the form of a my.cnf file.
  • 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 service apache2 restart

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

Translations can be installed:

$ sudo koha-translate --install language-code

To see all the language codes:

$ sudo koha-translate --list --available

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

Other commands

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

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, following those steps:

Install the Koha dependencies and the Java JDK

$ sudo apt install koha-elasticsearch openjdk-11-jdk-headless # openjdk-8-jdk-headless if you are using stretch

Download the Elasticsearch server (Version 6 is known to work, 7 is not supported yet)

$ wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-6.8.9.deb

Install it

$ sudo dpkg -i elasticsearch-6.8.9.deb

Install the analysis-icu plugin

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

Restart the serveur

$ sudo service elasticsearch restart

Wait a few seconds then check if it is running correctly

$ curl localhost:9200

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

Koha packaging information

Release policy

The stable package has a new release whenever the release maintainer for the current stable version creates a new version. As soon as a new major version is released, this will be updated with it too (within a couple of days ideally, anyway.)

The oldstable package has a new release whenever the release maintainer creates a new version. If a new major version version is released into stable, this will go up to the next major version that is behind stable. This means that you will get a new major release only after it's been out for several months and hopefully all the bugs have been found.

The unstable package is released whenever:

  • the package maintainer remembers to do it (every couple of weeks, typically. More sometimes.)
  • the current master branch is able to be built without errors.

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


Developer handbook

Personal tools