Koha on ubuntu - git

From Koha Wiki

Jump to: navigation, search
Home > Documentation
Home > Documentation > Installation
Home > Documentation > Installation > Installation alternatives
Home > Koha Versions > 3.10
Home > Koha Versions > 3.12
Koha > Technical > Administration
Koha > Technical > Administration



This is a shortened version of the Ubuntu Git Installation of Koha instructions. They have been tested. Use Ubuntu 14.04 LTS.

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

To install Koha for production, it is recommended that you use packages. To help assist with the development and improvement of Koha, continue with these instructions and read more about version control using git!

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

These instructions are intended for the impatient or those who are skilled. Each box can be cut and paste into the terminal window as needed. Some commands are split into separate boxes, because intermediate prompts occur.

These instructions set up a development system (master), not the current or former stable versions. As such, the install may not be as smooth as you wish. This is to be expected in a continually changing development system.

As this will load all branches, this could be more time consuming that using koha-gitify, which turns a package installation into a git version.

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 3.14.x series and the former stable version is the 3.12.x series.

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 Ubuntu_Packages_from_List section (koha-deps has the dependencies).

Add A Koha Community Repository

These instructions still function even though the latest version of Debian is wheezy. If the version has changed again, please confirm these instructions on the mailing list or IRC channel.

sudo ls
echo deb http://debian.koha-community.org/koha unstable 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 current stable release:
echo deb http://debian.koha-community.org/koha stable 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 the latest Koha release

Git is recommended for a development environment. Either a packages installation or a git installation can be used in a testing environment.

Install the base git installation first:

sudo apt-get install git git-email

Download Koha (make sure to substitute 'your name' and 'your@mail.com' appropriately):

git clone https://git.koha-community.org/Koha-community/Koha.git kohaclone
cd kohaclone
git config --global core.whitespace trailing-space,space-before-tab
git config --global apply.whitespace fix
git config --global color.ui auto
git config --global user.name "your name"
git config --global user.email "your@mail.com"
git checkout -b mywork origin/master

The git clone will download about 2.6GB (Jan 2016).

Install Dependencies

Ubuntu Packages from List

The repository added has koha-deps and koha-perldeps packages which make it very easy. Type the following:

sudo apt-get install koha-deps koha-perldeps make

If you encounter a problem, try consulting http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages#Appendix_B:_Troubleshooting
You will encounter issues related to running the web installation step. Refer to http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages#403_errors_for_Gitified_or_git_clone_installs

Ubuntu Packages for Perl Dependencies

Check everything was installed, by running the test script to identifty missing libraries:

./koha_perl_deps.pl -m -u

Install any required libraries that are missing. It is a good idea to install optional ones that are easily found as well.

Create MySQL Database and Grant Privileges

Create MySQL Database

If you have difficulty accessing MySQL's root acount, perhaps this Ubuntu page on resetting the root password may help.

mysql -u root -p

The Koha database has now been created with the name koha. It should now be listed.

Create User and Grant Permissions

Continue entering MySQL commands. Substitute a password of your choice for the {koha user password}'s in the following commands:

CREATE user 'kohaadmin'@'localhost' IDENTIFIED by '{koha user password}';
GRANT ALL ON koha.* TO 'kohaadmin'@'localhost' IDENTIFIED BY '{koha user password}';

The koha administrative user has now been created with the name kohaadmin and the password of your choosing.

Configure Koha

User/Group Environment Variables

Since there is no need to actually create a koha user account for a git installation. Just set some environment variables for the process to pick up and use later:

export __KOHA_USER__=$USER
export __KOHA_GROUP__=$USER
echo $USER

The output of the echo command should match your user id, and since the user id and group id are generally the same for a freshly created account, this will make sure the indexing happens as this account.

Generate Make file

Select defaults except as noted.

perl Makefile.PL

Answer dev to the first question.
Recall that the database created is koha whose name was set in the Create MySQL Database step. This is the default answer.
The username and password were set up in the Create User and Grant Permissions step. The username is the default answer, but only you know the password chosen.
Give some thought should be given to the MARC format desired and the method of character normalization (chr or icu), though the defaults will work as MARC21 just fine.
Use the same username and password for the Zebra questions.
Don't worry about warnings generated by optional components.

Build and Test Koha

Having configured Koha, build it using the following command:


Once this has successfully run, test Koha using the following command:

make test

If this fails, it is likely due to a failed dependency. Remember, this is a development system and dependencies are not always up to date. You can determine the dependency by scrolling back and looking for something like: Can't locate Cache/Memcached/Fast.pm in @INC

Re-run make test after installing the missing library. For example, after several runs you may have typed
sudo apt-get install libcache-memcached-fast-perl
sudo apt-get install libdbd-mock-perl

Install Koha

Once the make test has successfully run, install Koha using the following command (follow any on screen prompts):

$ make install

No sudo is required as you have access to the directories listed above.

Once this has successfully run, Koha is almost installed. There are only a few more steps left.

At the end of this command the output will look something like the following, where {your user name} is the user from which you are doing the installation:

Koha's files have now been installed.

In order to use Koha's command-line batch jobs,
you should set the following environment variables:

export KOHA_CONF=/home/{your user name}/koha-dev/etc/koha-conf.xml
export PERL5LIB=/home/{your user name}/kohaclone

For other post-installation tasks, please consult the README.

Take note of the two export commands as you will need them for a later step.

Pre-Web Install Setup

Ubuntu MySQL Security Tweak

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


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

Configure System Wide Environment Variables

Running scripts and cron jobs requires environment variables set. Use the following commands:

sudo nano /etc/environment


KOHA_CONF=/home/{your user name}/koha-dev/etc/koha-conf.xml
KOHA_PATH=/home/{your user name}/kohaclone
PERL5LIB=/home/{your user name}/kohaclone

Change {your user name} to your actual user name!


You will then need to log back in again.

Configure and Start Apache

Place Koha Site File

sudo ln -s ~/koha-dev/etc/koha-httpd.conf /etc/apache2/sites-available/koha.conf

NOTE: Exclude the .conf if you are using Apache 2.2 or earlier.

Tweak Koha Site File

The default file limits connections to those from (or, which is rather difficult to test/use in a server environment. Edit the file

sudo nano /etc/apache2/sites-available/koha.conf

/etc/apache2/sites-available/koha will have a line that should have the IP address changed to a *:

<VirtualHost *:80>

/etc/apache2/sites-available/koha will have another line that should have the IP address changed to a *:

<VirtualHost *:8080>

Setup Default Ports

sudo nano /etc/apache2/ports.conf

/etc/apache2/ports.conf must have two lines exactly like:

Listen 80 
Listen 8080

Do not add them if they are already there.

/etc/apache2/ports.conf does not require NameVirtualHost:

#NameVirtualHost *:80
#NameVirtualHost *:8080

Do not add them if they are missing or already there. Just prepend # accordingly.

Disable Default Site

These short instructions assume that the default site is not needed:

sudo a2dissite 000-default

If this is not the case, talk to your system administrator, network administrator, or IT Department.

Enable Modules and Site

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

sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2ensite koha
sudo service apache2 restart

Setup Zebra

Server to Start on Boot Up

sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
sudo update-rc.d koha-zebra-daemon defaults
sudo service koha-zebra-daemon start

Configure Zebra Indexing

crontab -e

add the following to the user cronjob

# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and gets set when this process runs.
*/5 * * * *	$KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null

Web Installation

You still need to configure/install Koha via the Admin Page. Navigate to:

If you do not know how to do this, try installing lynx:

sudo apt-get install lynx

Login with koha user name and password. See the Create User and Grant Permissions section above, and follow the steps.

Your page will be redirected to the login page after completing installation.

Setup Your Library in Koha

After the web install, you should be redirected to:

Login with koha user name and password.

Click on the More dropdown menu.

Select Administration.

Select "Libraries 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: 

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.

In order to upgrade, find the path to the koha install-log file:

find ~/koha-dev -name 'koha-install-log'

When upgrading from a previous installation of Koha 3, you can use the following from your current build directory:

perl Makefile.PL --prev-install-log /path/to/koha-install-log
make test
make upgrade

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 two commands which can take a long time (several hours) to complete for large databases:
    ./misc/maintenance/remove_items_from_biblioitems.pl --run

A full reindex is always a good idea too:

./misc/migration_tools/rebuild_zebra.pl -b -a -r -v

Uninstall Instructions

Remove Koha Apache Files

sudo a2dissite koha
sudo rm /etc/apache2/sites-available/koha
sudo /etc/init.d/apache2 restart

Disable and Remove Zebra Daemons

sudo update-rc.d koha-zebra-daemon remove
sudo rm /etc/init.d/koha-zebra-daemon
sudo update-rc.d koha-zebraqueue-daemon remove
sudo rm /etc/init.d/koha-zebraqueue-daemon

Remove MySQL Database

mysql -u koha -p > drop database kohadata;

Remove Zebra Indexes

sudo zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
sudo zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init

Remove Install Directories and Configuration Files

DISCLAIMER: The Command rm -r is an extremely powerful deletion tool. It will irrevocably remove what you tell it to. Use With Caution.

Crontab Entries

sudo rm -r /etc/cron.d/koha

Install Directories and Configuration Files

You may not want to delete kohaclone if you wish to reinstall later.

rm -r ~/koha-dev
rm -r ~/kohaclone
Personal tools