Updating Software in Koha

Amit Gupta

November 2010


Koha 3 Library Management System

Koha 3 Library Management System

Install, configure, and maintain your Koha installation with this easy-to-follow guide

  • A self-sufficient guide to installing and configuring Koha
  • Take control of your libraries with Koha library management system
  • Get a clear understanding of software maintenance, customization, and other advanced topics such as LDAP and Internationalization
  • Written in a style that applies to all Linux flavors and Koha versions


        Read more about this book      

Orientation to updating software

Before we can update the Koha software, let us learn about Koha's software versions and how to choose the version to upgrade to. In this section we also learn about the components of a software update, and how to install each component of the update properly.

Understanding Koha's software versions

To choose which new version to upgrade to, let us first understand how the Koha software is organized.


At any given point Koha has at least two main software branches:

  • Stable: This branch is older and is considered stable or bug free for the most part. Only bug fixes are allowed on this branch.
  • Development: This branch is where new features are developed. This branch is ahead of the stable branch, meaning it has all the features of the stable branch and the new features in development.


Both branches—stable and development have heads. A heads is the tip of the branch, pointing to the latest change made in that branch.

At the time of writing of this article, there are two heads available in Koha's Git repository.

  • 3.0.x: This is the tip of the stable branch
  • master: This is the tip of the development branch


Both branches have multiple tags. Tags point to specific points in a branch's change history. For instance we see these tags related to the stable branch:

  • v3.00.06: This is the latest stable branch
  • v3.00.05: An earlier version of the 3.0.x branch
  • v3.00.04: An earlier version of the 3.0.x branch
  • v3.00.03: An earlier version of the 3.0.x branch

And these tags are available for the development branch:

  • v3.02.00-beta: This is the 3.02 branch in the beta testing stage
  • v3.03.00-alpha: This is the 3.02 branch when released for alpha testing

Choosing a version to update to

We can choose to move to the head of the stable branch or the head of the development branch or to any tag in one of these branches.

Here are some pointers to help you decide:

  • On production servers, we upgrade to the latest stable tag in the stable branch
  • To take an early look at new features being developed, switch to the alpha or beta tag in the development branch, if available
  • If you want to take a look at the very latest version of the software, switch to head of the development branch

Understanding components of software updates

When bugs are fixed or new features are added in Koha, different types of files and programs can change such as these:

  • Perl, Java script, HTML, CSS, and other types of files in kohaclone folder
  • Tables, columns, constraints, indexes, system preferences, and other types of changes in Koha's database
  • Indexes and properties in Zebra configuration files
  • Directives in Koha's Apache2 configuration files

An overview of the installation process

To ensure that software updates are installed properly, we need to follow these steps:

  • Download software updates: We can download updates using Git. Git automatically detects our current version and downloads updates from Koha's online repository.
  • Switch to a specific software version: Depending on our purposes, we will choose a version that we want to upgrade to.
  • Install Perl module prerequisites: The new version of the software may depend on new Perl modules; we will need to install these.
  • Install the new version of Koha: We will install the new Koha version using the make utility; this process is similar to that of a fresh Koha install.
  • Configure Apache2: The new version of the software may have an updated Apache2 configuration file. We will need to configure this new file.
  • Upgrade the database: We will use Koha's web installer to upgrade the database to the new version.
  • Rebuild Zebra indexes: The new software version may contain updates to Zebra configuration files. To have these changes reflected in search results, we will need to do a full rebuild of Zebra's indexes.
  • Restart Zebra server: To load new Zebra configurations we will have to restart zebrasrv.
        Read more about this book      

Updating the software

Now that we have an understanding of how to update the software, let us go ahead and execute the update process.

Downloading updates using git pull command

To download software updates, we use the git pull command. Before we do that let us check what branch we are on at this time by using the git branch command:

koha@li190-245:~/kohaclone$ git branch
* koha-3.0.2

This * in the output above indicates that we are on the 3.0.2 version, which at the time of writing is an older version on Koha's stable branch.

Let us also check the branches on the online Koha repository, by using the git branch command with the –r (for remote branch) option:

koha@li190-245:~/kohaclone$ git branch -r
origin/HEAD -> origin/master

Of the several branches listed in the output above, two are of immediate interest to us—origin/3.0.x and origin/HEAD or origin/master. Origin/3.0.x is the stable branch while origin/HEAD or origin/master is the development branch.

If we are on a production server and we are interested only in updates for the stable branch, we will run the git pull command pointing to the stable branch—origin/3.0.x:

koha@li190-245:~/kohaclone$ git pull origin 3.0.x

If we are on a test machine, and we want to upgrade to the development branch for development of test purposes, we run the git pull command pointing to the development branch—origin/master:

koha@li190-245:~/kohaclone$ git pull origin master

Once the command is executed your Koha server has the latest updates available in the kohaclone folder.

Switching to a new software version

Now we need to decide which version of the software to use, this of course depends on what your purpose of upgrading is.

First let us take a look at the tags that are available. To determine this, we use the command git tag:

koha@li190-245:~/kohaclone$ git tag

We see several tags, at the bottom of the list; you should see tags for the 3.0.x branch, something like this:


And at the very bottom, tags for the master branch, which is currently versioned 3.02.xx:


To switch to the master or the head of the branch, we run the git checkout command as follows:

koha@li190-245:~/kohaclone$ git checkout master

We see from the output of the git tag command that the latest tag or version in Koha's stable branch is version v3.00.06. To switch to this version, we would run the git checkout command with the –b option and with a label for the new branch and the tag as parameters:

koha@li190-245:~/kohaclone$ git checkout -b <label for the new branch>
<tag pointing to the version>

The –b option creates a new branch with the specified label and points the branch to the software version specified by the tag. This command would be executed like this:

koha@li190-245:~/kohaclone$ git checkout -b koha-3.0.6 v3.00.06

To switch to tag 3.02.00-beta on the development branch, we would run the git checkout command as follows:

koha@li190-245:~/kohaclone$ git checkout -b koha-3.02-beta v3.02.00-beta

To test if you have switched branches successfully, use the git branch command:

koha@li190-245:~/kohaclone$ git branch
* koha-3.02-beta

Installing the new software version

Once we have switched to the software version we want to use, we will install the new Koha version in the same way that we do a fresh Koha install.

Running the Makefile.PL program

First we run the Makefile.PL program. As this is a software update and not a fresh install, we need to make sure we enter configuration details corresponding to the current installation:

linux-4yut:/usr/share/kohaclone # perl Makefile.PL

We chose the dev installation mode during our initial installation; make sure we choose the same here:

Installation mode (dev, single, standard) [standard] dev

Set the configuration directory to the directory configuration directory of the current installation:

Configuration directory: [/home/koha/koha-dev]

Make sure to specify the current database name here:

Please specify the name of the database to be used by Koha [koha]

Make sure to specify the current database name here:

Please specify the user that owns the database to be used by Koha

Specify the password of this MySQL user:

Please specify the password of the user that owns the database to be used
by Koha [katikoan] katikoan

If you are using Zebra, say yes here:

Install the Zebra configuration files? (no, yes) [yes]

For other questions, the default value should be fine. Simply press the Return key to proceed to the next step.

Installing Perl modules

The Makefile.PL step above may end with warnings on missing Perl module prerequisites:

[Mon Jun 14 16:12:27 2010] Makefile.PL: Warning: prerequisite IPC::Cmd
0.46 not found. We have 0.401.
[Mon Jun 14 16:12:30 2010] Makefile.PL: Warning: prerequisite
Text::CSV::Encoded 0.09 not found.
Writing Makefile for koha
linux-4yut:/usr/share/kohaclone #

We will need to install these missing modules using the package manager or the CPAN shell.

Completing Koha installation

Once all Perl modules are installed successfully, we finish the installation of the new version by running the rest of the make commands:

koha@li190-245:~/kohaclone$ make
koha@li190-245:~/kohaclone$ make test
koha@li190-245:~/kohaclone$ sudo make install

        Read more about this book      

Configuring Apache2

Installation of the new Koha version will overwrite Koha's Apache2 configuration file—/etc/koha-dev/etc/koha-httpd.conf. This is why we will need to configure Apache2 once again.

Upgrading the database

Once we have Apache2 configured we navigate to Koha's staff client to launch Koha's web installer. Here we use the kohaadmin MySQL user to log on.

Once we log in, we see a database upgrade message. In this step the installer will upgrade the database to match the new version of the software.

Once the database upgrade finishes, you should be able to log in to the new version of Koha.

Zebra—rebuilding indexes and restarting the server

As a final step we need to do a full rebuild of Zebra indexes in line with the new Zebra configuration files. We also restart zebrasrv to load the new configurations.

Rebuilding Zebra indexes

We run the rebuild_zebra.pl program with the –r option to do a full rebuild:

Linux-4yut:/usr/share/kohaclone # ./misc/migration_tools/rebuild_zebra.pl
-b –a -r -v
Restart Zebrasrv

Restarting zebrasrv

To restart zebrasrv, we restart the Zebra daemon as follows:

linux-4yut:/home/koha # sudo /etc/init.d/koha-zebra-daemon restart


Here is what we learned in this article on updating software:

  • Using git pull command to download software updates
  • Using git branch command to switch to a specific software version
  • Installing the new Koha version using the Make utility
  • Upgrading the database using Koha's web installer
  • Rebuilding Zebra indexes using new Zebra configuration files
  • Restarting Zebra server to load new configurations

You've been reading an excerpt of:

Koha 3 Library Management System

Explore Title