Koha on ubuntu - packages

From Koha Wiki

Jump to: navigation, search
Home > Documentation > Installation
Home > Documentation > Installation > Debian Packages
Koha > Technical > Administration
Koha > Technical > Administration



As of November 2016, the Debian packages for Koha are based on Jessie (Debian 8). Xenial (Ubuntu 16.04 LTS) is based on Jessie.

That means Ubuntu 14.04 LTS is no longer supported.

These are the package installation instructions for Ubuntu. They have been tested using Ubuntu 16.04 LTS.

There are problems on Ubuntu 16.04. See: Ubuntu_16.04_and_MySQL_5.7

nano is a generic text editor. Please feel free to substitute your favourite editor (vi, emacs, gedit, or etc.).

To help assist with the development and improvement of Koha, consider installing a git version. Try to learn version control using git!

Do not attempt to correct tarball or git problems by following these instructions.

These instructions are intended for the impatient or those who are skilled. The word library is the instance name and can be substituted with whatever is desired. Each box can be cut and paste into the terminal window as needed. Some commands are split into separate boxes, because intermediate prompts occur.

Pre-Installation Setup


For the most part, the boxed text is what goes on the command line or an MySQL prompt. However, when the box contains what you should see in a file (fully or partially), the file name will be bolded above the box.

Koha is released monthly, so keeping documentation up to date is difficult. The convention is to replace the last number with an x. For example, the current version is part of the 16.05.x series and the former stable version is the 3.22.x series.

The versioning method has changed to YY.MM.x format reflecting YY.05 or YY.11 as stable releases, and YY.06 or YY.12 as the development release. Previously, R.even were stable and R.odd were development releases. The 3.22.x series was the last one under the older versioning method.

Install Ubuntu

Download and install Ubuntu from the official site.

Do not install extra packages during Ubuntu installation. Apache2 and MySQL will be installed in the instructions later.

Add A Koha Community Repository

If there are problems with these repositories, please confirm these instructions on the mailing list or IRC channel.

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

To use the older stable release: echo deb http://debian.koha-community.org/koha oldstable main | sudo tee /etc/apt/sources.list.d/koha.list
or to use the development release: echo deb http://debian.koha-community.org/koha unstable main | sudo tee /etc/apt/sources.list.d/koha.list

Add the key in gpg.asc to your APT trusted keys to avoid warning messages on installation:

wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

Update Ubuntu

This process, particularly the upgrade step, may take a while.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get clean

Download and install the latest Koha release

sudo apt-get install koha-common

If you encounter problems, see Appendix B.

Pre-Web Install Setup

Initial Configuration

To configure your server for use, edit /etc/koha/koha-sites.conf with details about your site. You may need to create this file. The contents of this file affect any Koha instances created on this server, so verify settings before creating an instance.
You can use as a reference the file on /etc/koha/koha-sites.conf.dpkg-new.

As an example, suppose you want to create an instance named mykoha with the domain names and ports set like this:

  • OPAC: mykoha-opac.mydomain.org:80 (port 80 is the default for web sites)
  • Intranet: mykoha-admin.mydomain.org:8080 (a different port that can be filtered)

You would set DOMAIN=".mydomain.org", INTRAPORT="8080", INTRASUFFIX="-admin", OPACPORT="80", OPACSUFFIX="-opac". See Appendix_A for a discussion of Name-based vs. IP-based installation, and Base_Install_Finished for an example of the how these affect the URL.

sudo nano /etc/koha/koha-sites.conf
 # Apache virtual hosts creation variables
INTRAPORT="80"               # use 8080 for an IP-based install.

 # SQL file to load into new instances

 # Zebra global configuration variables
ZEBRA_MARC_FORMAT="marc21"   # or normarc or unimarc.
ZEBRA_LANGUAGE="en"          # match with installation language (e.g. es for Spanish)

 # Memcached global configuration variables

Please see your Network Administrator to clarify any uncertainties for the DOMAIN entry.

Instance Creation

These instructions assume a local database installation.

Ubuntu 16.04 and MySQL 5.7

On Ubuntu 16.04 now (Nov. 2016) is present MySQL 5.7. All versions of Koha are not compatible with default config of MySQL 5.7. To bypass the problem you can:

  1. Install MariaDB instead of MySQL:
    sudo apt-get install mariadb-server
  2. OR
    • Install MySQL server:
      [ sudo apt-get install mysql-server ]
    • AND Insert in your /etc/mysql/mysql.conf.d/mysqld.cnf in the [mysqld] section:
    • After save the changes and restart mysql.

The koha-create command writes out Apache configuration files. It requires the Apache mod_rewrite module to be enabled:

sudo a2enmod rewrite
sudo a2enmod cgi
sudo service apache2 restart
  • The library is the instance name, and can be changed to anything required. It will affect the resulting URL. See Base_Install_Finished for an explanation of the URL.
  • include --use-memcached if memcached will be used. This may need to be installed first with: sudo apt-get install memcached
sudo koha-create --create-db library

Ubuntu MySQL Security Tweak

There is a security risk in Ubuntu's MySQL default set up. Type the following commands:

sudo mysql_secure_installation

The 'n' answer is case sensitive. You likely already set the root password when you installed MySQL. So the first answer is 'n'. The rest are all the default 'Y' (yes).

Configuring Apache

Setup Default Ports

These instructions assume port 80 was used for INTRAPORT and OPACPORT. Changing values requires understanding Apache configuration files, which is beyond the scope of this document. Type the following command:

sudo nano /etc/apache2/ports.conf

/etc/apache2/ports.conf should contain one line like (do not delete lines!):

Listen 80
  • Add it if it is missing. Comments start with #, remove the # if they are commented out.
  • Add also Listen 8080 (or whatever other port was chosen in the Initial Configuration section) if IP-based installation for intranet access.
  • Further educational reading: Apache Binding to Addresses and Ports

Enable Modules and Site

Now enable the apache modules this config needs, enable koha's configuration, and restart apache.

sudo a2enmod deflate
sudo a2ensite library
sudo service apache2 restart

If you encounter problems enabling the site, checkout Appendix B.

Determining an IP Address


In a home or corporate LAN, it is quite likely that your network setup has been configured with DHCP. If you are being hosted externally however, your machine likely has been given a static IP address, or it may be behind a reverse proxy. Because of the many possible complex configurations of networking involved, these instructions will attempt to guide you in the former simpler case. If you are unable to get to the Web Installation step or access Koha from another machine, please consult your system administrator, network administrator, or IT Department. We are unable to assist everyone with their networking configurations.

Tweak Hosts File

The default configuration for the packages installation is based on fully qualified domain name set up. Since your fully qualified domain name may not be active yet, edit the /etc/hosts file to include it:

sudo nano /etc/hosts

/etc/hosts should have these two lines added (do not replace!):		library.myDNSname.org		library-intra.myDNSname.org

If you know the IP address, edit any other machine's /etc/hosts file with that IP address instead of

Building Languages

You may wish to install a variety of languages. If so, build them now using the appropriate language code.
Check if your language code is available with koha-translate --list --available
For example, to install France French: sudo koha-translate --install fr-FR

Web Installation

Now you can visit your admininstration website to continue with the Koha web installer. The username to log in with will be koha_library.
and you can get the password from this command

sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml;echo

Navigate to your staff client page. You can do this by installing lynx and going there on your koha machine:

sudo apt-get install lynx

Lynx navigational keys include: tab to go between fields, enter (when not on text fields) to toggle or click, space to change pages (when not on text fields), Q to quit (when not on text fields). Arrows also work.

lynx http://library-intra.myDNSname.org:80

Setup Your Library in Koha

After the web install, you should be redirected to the staff client login screen.

  • Login with koha user name and password.
  • Click on the More dropdown men and then on Administration.
  • Select Libraries, branches and groups under the "Basic Parameters" heading.
  • Click New Library and enter your information into the form.
  • Click Submit.

Your Library is now setup in Koha.

Base Install Finished

The staff client, or administrative page, can be accessed at:


The OPAC, or client page, can be accessed at:


Where the values of {DOMAIN}, {INTRAPORT}, {INTRAPREFIX}, {INTRASUFFIX}, {OPACPORT}, {OPACPREFIX}, and {OPACSUFFIX} were defined in the Initial Configuration step, and {InstanceName} was defined in the Instance Creation step, though the example given said library.

You should now have a functional Koha Installation

Upgrade Instructions

If you are running in another language other than English, please switch to English before doing the upgrade, the templating system has changed and the templates will need to be regenerated. Once you have upgraded, please regenerate your templates in your chosen languages.

sudo apt-get update
sudo apt-get upgrade

This should generally upgrade your koha-common. However, if the dependencies for koha have increased, you may have to:

$ sudo apt-get install koha-common

Koha 3.4.x or later no longer stores items in biblio records. If you are upgrading from a version older than Koha 3.4.x, run the following command which may take a long time (several hours) to complete for large databases: koha-upgrade-to-3.4

It is always safest to run a full reindex after an upgrade, where {instance} is the name of your instance:

koha-rebuild-zebra -v -f {instance}

Uninstall Instructions

The package installation method is unique in that a removal command is already provided. Determine what instances you have:

$ koha-list

And then for each instance:

$ sudo koha-remove {instance}

If you encounter any problems, please request help on the mailing list or IRC channel.

After uninstalling all the instances, uninstall the koha-common package:

$ sudo apt-get remove koha-common

Appendix A: Named-based vs. IP-based installations

These instructions are for a name-based installation. If you do not understand editing hosts files, do not have any IT support whatsoever, and are unable to get past a "Server not found" error, or the OPAC maintenance screen, then you likely wish to do an IP-based installation.

The koha-site.conf file that was created is for a name-based installation. Apache can tell whether you want the staff client or the OPAC based on the name you use. However, if you do not have a DNS entry and editing hosts files for every single machine in the world sounds unpleasant, then you likely want an IP-based installation.


# Apache virtual hosts creation variables 

# 80 may have "It Works!" problems.
# default site could be used by other applications

# SQL file to load into new instances

# Zebra global configuration variables

# Memcached global configuration variables

This means that the OPAC client with be at http://ipaddress:8081/ The staff client will be at http://ipaddress:8080/

And assuming you use library as your instance name, if you do get around to having a proper NAME using DNS:

Appendix B: Troubleshooting

Because of the way Apache 2.4 changed from 2.2, issues arose. As a result, you will likely encounter solvable issues with both Ubuntu 12.04 LTS server and Ubuntu 14.04 LTS server. At this point in time, the Ubuntu 14.04 LTS Apache issues are recommended.

Some difficulties were encountered installing apache2-mpm-itk.

Launchpad has a bug report with some suggested steps that resolved the problem under Ubuntu 14.04:

sudo a2dismod mpm_event
sudo a2enmod mpm_prefork
sudo service apache2 restart

If this was during an installation of koha-common:

sudo apt-get install -f

Apache site-available issues

When attempting to enable an apache site, it supposedly doesn't exist. Depending on the version of apache installed, sites of one form (e.g. /etc/apache2/sites-available/{SITENAME}) need to be renamed to another form (e.g. /etc/apache2/sites-available/{SITENAME}.conf). This should solve potential issues when you try to enable the site later in the instructions. Both on Apache 2.2 and 2.4, on a normal case you could disable a library instance with the command a2dissite library.conf && service apache2 reload.

403 errors for Gitified or git clone installs

In Ubuntu 14.04 you may discover that your gitified install returns 403 errors - this is because of the changes to Apache directory security. A possible fix includes adding the following stanza to apache2.conf (could be added in the virtualhost, or in one of the koha-shared*.conf files as well):

<Directory /home/my-user/koha-src/koha/>
     Options Indexes FollowSymLinks
     AllowOverride None
     Require all granted

AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using Set the 'ServerName' directive globally to suppress this message

Solution for Ubuntu 14.04:

echo "ServerName localhost" | sudo tee /etc/apache2/conf-available/fqdn.conf
sudo ln -s /etc/apache2/conf-available/fqdn.conf /etc/apache2/conf-enabled/fqdn.conf

AH00548: NameVirtualHost has no effect and will be removed in the next release /etc/apache2/ports.conf

Solution: Comment out: #NameVirtualHost *:80

It Works!

Your Apache configuration needs fixing, read Apache Virtual Hosts and Apache Port documentation.

Personal tools