WARNING! This page is obsolete.
Please use the Koha_on_Debian guide for installing Koha packages on Ubuntu.

Introduction

Note: Ubuntu 16.04 support will reach end of life with Koha versions 18.11.18, 19.05.12 and 19.11.06.

Ubuntu 14.04 LTS or earlier has not been supported since 2016.
These are the package installation instructions for Ubuntu. They have been tested using Ubuntu 16.04 LTS.
For Bionic (Ubuntu 18.04 LTS), see this thread http://koha.1045719.n5.nabble.com/Koha-on-Ubuntu-18-04-LTS-Bionic-Beaver-td5975633.html

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

Notation

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 Server (which is based on Debian) from the official site.

Server edition (command-line only)

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.

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- https://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

If this command complains "gnupg, gnupg2 and gnupg1 do not seem to be installed, but one of them is required for this operation", then install them and try again:
sudo apt install gnupg gnupg1 gnupg2

Update Ubuntu

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

sudo apt update
sudo apt upgrade

sudo apt clean

Download and install the latest Koha release

sudo apt 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
DOMAIN=".myDNSname.org"
INTRAPORT="80"               # use 8080 for an IP-based install.
INTRAPREFIX=""
INTRASUFFIX="-intra"
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
 # SQL file to load into new instances
DEFAULTSQL=""
 # Zebra global configuration variables
ZEBRA_MARC_FORMAT="marc21"   # or normarc or unimarc.
ZEBRA_LANGUAGE="en"          # match with installation language (e.g. es for Spanish)
BIBLIOS_INDEXING_MODE="dom"
AUTHORITIES_INDEXING_MODE="dom"
 # Memcached global configuration variables
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"

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

Instance Creation

These instructions assume a local database installation.

MariaDB or MySQL

You can either install MariaDB

 sudo apt install mariadb-server

OR 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

Apache modules

The koha-create command writes out Apache configuration files. It requires the Apache mod_rewrite and mod_cgi modules 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.

sudo koha-create --create-db library

Ubuntu Database Security Tweak

There is a security risk in Ubuntu's default set up (for MariaDB and MySQL). Type the following command:

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

Assumptions

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!):

127.0.0.1		library.myDNSname.org
127.0.0.1		library-intra.myDNSname.org

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

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

If this gives a strange DBI connection error message, attempt to restart memcache (sudo service memcache restart) and try again.

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:

http://{INTRAPREFIX}{InstanceName}{INTRASUFFIX}{DOMAIN}:{INTRAPORT}

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

http://{OPACPREFIX}{InstanceName}{OPACSUFFIX}{DOMAIN}:{OPACPORT}

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

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

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}

On your librarians clients consider clear browser cache after upgrading.

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.

/etc/koha/koha-sites.conf

# Apache virtual hosts creation variables 
DOMAIN=".myDNSname.org"
INTRAPORT="8080"
INTRAPREFIX=""
INTRASUFFIX=""

# 80 may have "It Works!" problems.
# default site could be used by other applications
OPACPORT="8081"
OPACPREFIX=""
OPACSUFFIX=""

# SQL file to load into new instances
DEFAULTSQL=""

# Zebra global configuration variables
ZEBRA_MARC_FORMAT="marc21"
ZEBRA_LANGUAGE="en"
BIBLIOS_INDEXING_MODE="dom"
AUTHORITIES_INDEXING_MODE="dom"

# Memcached global configuration variables
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"

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:

http://library.myDNSname.org:8081 will be the OPAC
http://library.myDNSname.org:8080 will be the Staff client.

Appendix B: Troubleshooting

Because of the way Apache 2.4 changed from 2.2, issues arose. As a result, you may likely encounter solvable issues. These are the recommended solutions.

perl: warning: Setting locale failed.

dpkg reconfigure locales

This will give you the ability to regenerate all the locales, so there can not possibly be able problems next time. Or, if there is time and energy to attempt, figure out which ones to check minimally to not trigger the issue.

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
</Directory>

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

Solution for Ubuntu 16.04:

echo "ServerName localhost" | sudo tee /etc/apache2/conf-available/fqdn.conf
sudo a2enconf fqdn

test with

apachectl configtest

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.