Installation of Koha 3.x on Debian Squeeze


 Debian packages of Koha

There is an APT package repository for Debian packages of Koha, and those of its dependencies that are missing from Debian. The Debian squeeze (6.0) and wheezy (7.0) releases are supported; older versions of Debian are not supported. Ubuntu tends to work too, though see the notes about Ubuntu 14.04 at the bottom.

At the moment, the ‘koha-common’ package is preferred to the ‘koha’ package.


There are three versions of Koha packaged:

  • one stable release (3.16)
  • one old-stable release (3.14)
  • one development release

If you’re unsure what you want, go for the stable version. If you want to be a bit more conservative, go for the most recent old-stable release.

To use

At this stage, the package usage of the three versions is pretty much identical. There is only difference is where you choose which one you want.

There is also a handy walkthrough on installing and configuring the packages.

Old Stable Version

To get the old stable 3.14 release, add this to a /etc/apt/sources.list.d/koha.list file:

   deb oldstable main

Current Stable Version

To get the stable 3.16 release, add this to a /etc/apt/sources.list.d/koha.list file:

   deb squeeze main

Development Version

To get the development release (currently from 3.17), add this to your /etc/apt/sources.list.d/koha.list file:

   deb squeeze-dev main


Add the key in gpg.asc to your APT trusted keys:

   wget -O- | sudo apt-key add -

(If you are familiar with GnuPG, you will want to verify that you have a trust path to the key. If you do not know how to do that, this space is unfortunately too limited to explain how and you will have to take your chances.)

After that, you should be able to install Koha:

   sudo apt-get update
   sudo apt-get install koha-common
   less /usr/share/doc/koha-common/README.Debian

Read the README.Debian file for instructions on how to configure Koha after the package is installed.

Wait! Why is there no koha package? Well, there is but it’s not in this repo because it’s not complete:

  • koha-common contains all the code and support scripts. It won’t give you a koha instance that is up and running on installation, but it does allow you to use koha-create and associated tools to create as many instances as you want. Anything created with this command will automatically be managed by cron jobs, and zebra will work, and so forth.
  • koha is similar, but provides a single site. At the moment however, this site can’t be managed by the tools that come with the package, and so you will need to set up the cron jobs and zebra for it yourself. See bug 5071 for plans to fix this. It is not recommend that you use this package yet.

Quick Start

Initial Configuration

This assumes that you are using the koha-common package.

To configure your server for use with DNS names: After install, edit /etc/koha/koha-sites.conf with details about your site. You may need to create this file.

If you don’t need DNS configuration and want to access Koha via IP only (often done for test installations), you can skip creating this file and you will get default values (OPAC on port 80 and Staff client on port 8080).

Some example content would be:

DOMAIN=""  # Any library instance will be a subdomain of this string.
INTRAPORT="80"  # TCP listening port for the administration interface
INTRAPREFIX=""  # For administration interface URL: Prefix to be added to the instance name.
INTRASUFFIX="-intra"  # For administration interface URL: Suffix to be added to the instance name.
DEFAULTSQL="/usr/share/koha/defaults.sql.gz"  # only needed if you're pre-populating from another Koha database
OPACPORT="80"  # TCP listening port for the users' interface (if you skip this, the apache default of 80 will be used)
OPACPREFIX=""  # For users' interface URL: Prefix to be added to the instance name.
OPACSUFFIX=""  # For users' interface URL: Suffix to be added to the instance name.
ZEBRA_MARC_FORMAT="marc21"  # Specifies format of MARC records to be indexed by Zebra. Possible values are 'marc21', 'normarc' and 'unimarc'
ZEBRA_LANGUAGE="en"  # Primary language for Zebra indexing. Possible values are 'en', 'fr' and 'nb'

Next, you will need to enable the Apache mod_rewrite module:

sudo a2enmod rewrite

If you are planning to run MySQL on the same server as you are running Koha on, then make sure you install it:

sudo apt-get install mysql-server

If you’re planning to run MySQL on a separate server, please do not run koha-create --create-db instancename as mentioned below. Instead, see Install Koha 3.6 on Debian squeeze using a separate MySQL server.

Creating the Koha Instance

Now you need to create your first koha instance. Replace instancename with the name of your library. If you want to have, then instancename can probably be “library”.

sudo koha-create --create-db instancename

Now you can visit your admininstration website to continue with the Koha web installer.

The username to log in with will be koha_instancename and the password will be near the end of /etc/koha/sites/instancename/koha-conf.xml. You will need to be root to view this You could also use this command:

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

to print it out.

Building Languages

Commands to build a language for interface (example for france french):

sudo koha-translate --install fr-FR

Commands to build all available languages for interface:

cd /usr/share/koha/misc/translator
Langs="$(ls -1 /usr/share/koha/misc/translator/po/ | grep -ie "pref.po" | sed -e "s/-pref\.po//g")"
for Current in $Langs ; do sudo env PERL5LIB=/usr/share/koha/lib KOHA_CONF=/etc/koha/sites/instancename/koha-conf.xml perl translate install $Current ; done


koha-common installs a number of handy commands, which are still somewhat underdocumented. Here is an overview of these:

  • koha-create: create a new library instance. For example koha-create --create-db mylibrary will create a new koha catalogue called ‘mylibrary’, create and populate the database for it, set up zebra, and configure Apache appropriately. Note that by default after creation, your Koha instance may be disabled. If you get “command not found”, try /usr/sbin/koha-create (It’s possible that that isn’t on your $PATH).
    • There are a number of options to koha-create that allow you do to things such as set your MARC flavour and language for zebra.
  • koha-enable/koha-disable: this lets you enable or disable a Koha instance, e.g. koha-enable.
  • koha-email-enable/koha-disable-email: turn on or off sending of email for the Koha instance. If email is disabled, the mail queue is regularly cleared in order to prevent a wave of emails when its turned on. Note: by default, a new Koha instance has the mail disabled.
  • koha-remove: deletes a Koha instance

See also: Commands provided by the Debian packages.

Other packages

This repository may also contain other packages that Koha needs, but which are missing from Debian squeeze. The list of packages will vary over time, as new packages are needed and before they get uploaded to Debian. After they are in Debian squeeze, they get removed from this repository.

On Debian you may need to install sudo, i.e. apt-get install sudo.

When installing on Ubuntu the following instructions may help : Koha_on_ubuntu_-_packages

Update policy

There is a need for packages of both the stable Koha release and the tip of the git master branch. One is useful for running Koha in a production environment, the other is useful for testing and developing Koha, and for preparing for upgrades.

This creates a risk that all the configuration management will become overwhelming. There is a strong need to keep things simple.

For simplicity, only Debian squeeze will be targeted for now. Also, for now, all packages are built and uploaded by Robin Sheat (, until there is a need to set up an actual upload queue.

There is one repository. It has two pockets (for now):

  • squeeze: for packages intended for production use
  • squeeze-dev: for things that are still undergoing development

Both Koha packages and dependencies go into the same pockets.

The Koha packages in the squeeze pocket are built from the 3.16.n tag, and the packages in squeeze-dev are build from master.

Making changes to the Debian packaging

To make changes to the Koha Debian packaging in the Koha master branch, changes will happen as they would for any other part of Koha: submit it as a patch, and hope that the release manager accepts it. When it is accepted, Robin will will actually build and upload the packages.

For simplicity, it is important to not break the symmetry between the Koha master branch and the packages uploaded to

Supporting more Debian releases

It is possible, but quite a bit of effort, to support Debian lenny. The problem is that there is a lot of software Koha needs that are not packaged for lenny, so they would have to be backported and added to the Koha apt repository. If someone is willing to do the backporting and taking responsibility of keeping them updated, Robin is willing to arrange them to get included in the repository.

For Debian releases other than squeeze, we will need to add more pockets. Every package will need to be built for each release separately, but that can be automated, at least mostly. There might be a need to do parts of the packaging differently on each release, and this will be a bit of a nightmare. It Robin’s sincere hope we do not need to worry about this for a while, and that we can solve the problem when we get it, and not now.

Building Your Own Packages

If you want to build your own packages for internal use, the process used for building the these can be adapted. You can find it here. Or see Building Debian Packages – The Easy Way.

Issues of note

a freshly updated debian – Lenny to Squeeze – might sometimes have trouble with the debian-sys-maint mysql user. You can fix it by following the instructions

Troubleshooting Ubuntu 14.04

There are some bugs in the Apache configuration in Ubuntu 14.04.

  • If you see:
Errors were encountered while processing:

Then run:

sudo a2dismod mpm_event
sudo apt-get install -f
  • If you try to access Koha, but you get a file save dialogue box from your browser, then run:
sudo a2enmod cgi
sudo service apache2 restart

See also


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s