Professional Documents
Culture Documents
Koha On Debian - Koha Wiki
Koha On Debian - Koha Wiki
Koha On Debian - Koha Wiki
Contents
1 Before you begin
2 Debian packages on Koha
2.1 Installation process
2.1.1 Set up package sources
2.1.2 Pick which Koha version to follow
2.1.2.1 Follow a suite: stable, oldstable …
2.1.2.2 Follow a codename (version number): 21.05, 20.11, 20.05, 19.11
2.1.2.3 Support for Koha on older versions of Debian/Ubuntu (Debian 8, Ubuntu 18.04, Ubuntu
16.04)
2.1.3 Install Koha
2.1.3.1 Aside: a common problem on Ubuntu happens here
2.1.4 Install the database
2.1.5 Configure the defaults
2.1.6 Set up Apache
2.1.7 Create a Koha instance
2.1.8 Setup plack
2.1.9 Access the web interface
2.1.9.1 If you encounter timeout errors
2.2 Further configuration
2.2.1 E-mail
2.2.2 Translations
2.2.3 Seaching and non-latin languages
2.2.4 Other commands
2.2.5 Services
2.2.6 MySQL and MariaDB
2.2.7 Elasticsearch
2.2.8 Anacron
2.3 Upgrade
2.4 Koha packaging information
2.4.1 Release policy
2.4.2 How koha-create configures your system
2.4.3 Packaging releases
2.4.4 Other things
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.
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 '$'.)
Add the GPG key to your system so that you know that the packages haven't been tampered with:
Pick what version of Koha you want. You can either follow by codename (version number), or by suite.
If you follow a suite, you will automatically upgrade to a newer branch each release cycle.
If you follow a codename (version number), you will stay on that branch until you change your apt configuration to follow
another.
If you have set "20.05" in your apt configuration, you will stay on 20.05 until you change your apt configuration to follow
20.11.
No new Debian packages will be released for the following Koha versions. Please upgrade to a newer version of Koha.
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
Install Koha
libapache2-mpm-itk
apache2-mpm-itk
koha-common
Then do this:
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
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
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
You will only need the second Listen entry, if you have chosen to make the staff interface accessible on a different port.
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
then:
You will need to have your DNS set up for this. The default hostnames are:
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.
koha_libraryname
randompasswordtext
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:
Translations
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.
Due to how MySQL behaves with AUTO_INCREMENT values you should take a look at this dedicated wiki page to fix
potential issues.
Elasticsearch
$ 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
$ curl localhost:9200
Switch the system preferences SearchEngine to 'Elasticsearch' then index your records
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
Upgrade
If you installed Koha as described above, an upgrade should be as easy as this:
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.)
If you want to upgrade to a newer major version (e.g. from 19.11.x to 20.05.x) you 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:
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:
Remember to always scan the output of these commands for any error messages related to the upgrading of the Koha
database.
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 package maintainer remembers to do it (every couple of weeks, typically. More sometimes.)
the current master branch is able to be built without errors.
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
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 (http://dashboard.koha-community.org/) | Bugzilla (http://bugs.koha-
community.org/bugzilla3/) | Schema (http://schema.koha-community.org/) | perldoc (http://perldoc.koha-
community.org/) | Jenkins (http://jenkins.koha-community.org/)