Implementation Checklist

The following guide will walk you through the areas of Koha you need to look at in order to prepare to start using the system.

Data Migration

Before you can start using Koha you’ll need to have some data. This can be done by entering it all by hand, but most people already have their data in electronic format of some sort and just need to reformat it a bit for importing into Koha.

  • Create a list of libraries and enter their info and codes into Libraries & Groups
  • Define your list of Item Types
  • Define your patron categories and enter the categories and their codes into Patron Categories
  • Enter any additional patron information fields you use in your library in the Patron Attributes
  • Define all of your Authorized Values
  • Optionally define City/State/Postal Code combos
  • Map your bibliographic data from your legacy system to Koha fields and migrate (remembering to use the collection, shelving, item type and library codes you entered in the above setting areas)
  • Map your patron data from your legacy system to the Koha fields and migrate (remembering to use the patron and library codes you defined above)
  • Test your migrated data to be sure that everything is as you expect it to be, some things to test include:
    • Check some of your titles with diacritics and make sure that they migrated properly.
    • Check titles in a series and make sure that series information migrated properly.
    • Make sure that your patrons have their contact information in the right fields.
    • If your serials data was migrated search for these records in the catalog and confirm that they look right.
    • If your serials data was migrated search for these records in the serials module and confirm that they look right.
    • Check marc records to verify a variety of items are cataloged correctly
    • Check cataloging process to see if all necessary fields are available
    • If fines are migrated, check to see that they are applied correctly
    • If holds are migrated, check to see they are accurate in catalog and patron record

Admin Configuration

Most of these preferences won’t need to be changed to use your Koha system, but there are a few that you might want to customize.

Localization Configuration

Koha is used worldwide and so you need to make sure you set your localization preferences so that options throughout Koha appear properly for your location/language.

  • Localization/Internationalization System Preferences

Circulation Configuration

Before you start circulating your collection you’ll need to set up your rules and preferences for circulation.

Patron Configuration

You have already imported patron data from your old system, but there are plenty of options available to you regarding patrons and their accounts.

Cataloging Configuration

Before you start cataloging in Koha you’ll want to set up your preferences and other rules.

Authorities Configuration

Koha has the ability to keep track of your authority records and how they’re linked to your bibliographic records. Before using authorities you should configure several preferences.

Searching Configuration

There are several system preferences related to searching, it is not always recommended to make too many changes to these preferences since they are set to get you the most relevant results. If you would like to change the default way that Koha handles searching, view the Searching system preferences tab.

OPAC Configuration

There are a lot of ways you can customize your OPAC in Koha.

  • Decide how you want your OPAC to look & what content you want on the main page

  • Create a library branded stylesheet using CSS

    • Important

      Do not edit the default CSS files, instead create a new one, that way the system can always fall back on the original CSS.

  • Create a custom XSLT stylesheet to change the way search results and bib records appear in the OPAC

  • OPAC System preferences

    • OPACBaseURL : Enter your library’s url
    • opacuserlogin : Decide if you want to allow patrons to login to the OPAC to access customized functionality (searching will be allowed without logging in)
      • RequestOnOpac : Decide if patrons can place holds via the OPAC
      • OpacPasswordChange : Decide if patrons can change their password (don’t allow this if you’re using LDAP)
      • OpacRenewalAllowed : Decide if patrons can renew their checked out items via the OPAC
      • opacreadinghistory : Decide if patrons can view their reading/checkout history via the OPAC
      • reviewson : Decide if you want to allow patrons to comment on bib records via the OPAC
      • OpacStarRatings : Decide if patrons can leave star ratings
      • virtualshelves : Decide if you want patrons to be able to create Lists
      • OpacAllowPublicListCreation : If patrons can create lists then decide if they are allowed to create public lists
      • suggestion : Decide if you want patrons to be able to submit purchase suggestions
      • OPACViewOthersSuggestions : Decide if you want patrons to be able to see purchase suggestions made by other patrons
    • opacbookbag : Decide if patrons can save items into their cart
    • AnonSuggestions : Decide if you want non logged in users to be able to make purchase suggestions
    • LibraryName : Enter your library name for display in the <title> tag and on the top of the OPAC
    • opaccredits : Enter HTML to appear at the bottom of every page in the OPAC
    • OpacMainUserBlock : Enter HTML that will appear in the center of the main OPAC page
    • OpacNav : Enter HTML that will appear to the left on the main OPAC page
    • OpacNavBottom : Enter HTML that will appear below OpacNav
    • OpacNavRight : Enter HTML that will appear below the login box on the right
    • opacheader : Enter the HTML that will appear above the search box on the OPAC
    • OPACNoResultsFound : Enter the HTML that will appear when no results are found
    • OPACResultsSidebar : Enter the HTML that will appear below the facets on your search results
    • OPACMySummaryHTML : Enter the HTML that will appear in the far right of the circulation summary in the OPAC
    • Customize your stylesheets:
    • OpacHighlightedWords : Decide if you want search terms to be highlighted on the search results
    • hidelostitems : Decide if you want to show patrons items you have marked as lost
    • BiblioDefaultView : Decide what view is the default for bib records on the OPAC
    • OPACShelfBrowser : Decide if you want to enable the shelf browse functionality
    • OPACURLOpenInNewWindow : Decide if URLs clicked in the OPAC are opened in a new window
    • SearchMyLibraryFirst : If you have a multi-branch system decide if you want patrons to search their library first
    • OpacAuthorities : Decide if you want patrons to be able to search your authority file
    • OpacBrowser : Decide if you want patrons to browse your authority file (French libraries only)
    • OPACSearchForTitleIn : Choose which libraries you want patrons to be able to re-run their search in
    • OpacAddMastheadLibraryPulldown : If you’re a multi-branch system you can add a pull down to the search bar for patrons to search which library to search
    • EnableOpacSearchHistory : Decide if you want the system to keep a search history
  • Set up your cron jobs

Editable OPAC Regions

Using the OPAC system preferences you can customize various regions, the following graphic will define what preferences update each of the regions in the Bootstrap theme.

OPAC Editable Regions image1068

Enhanced Content Configuration

Koha allows you to pull in content from outside sources to enhance your bib records. All of this content can be toggled on and off using the enhanced content system preferences.

  • FRBR/Editions
    • If you would like to have your OPAC and/or staff client show an ‘Editions’ tab on the bib record, you want to enable one or the other FRBR preferences and then either one or both of the ISBN services (XISBN and ThingISBN).
  • Amazon : This service is free and just requires that you visit to sign up
    • Using the Amazon preferences you can choose to show cover images from Amazon.
  • Babelthèque
    • This is a pay service. Contact Babelthèque to learn how to enable this content in the OPAC.
  • Baker and Taylor
    • This is a pay service from Baker & Taylor. Contact Baker & Taylor for the information to enter into these preferences.
  • HTML5 Media
    • This allows libraries to embed streaming media in their catalog
  • Google
    • This service is free and does not require registration, simply enable GoogleJackets and you’re set to go.
  • I Deam Books
    • This is a free service that compiles reviews for popular titles from many different sources.
  • LibraryThing
    • With the exception of ThingISBN, you will need to contact LibraryThing for the information to enter into these preferences
    • Enabling ThingISBN will help to populate the editions tab on the bib record display if you have enabled FRBR.
  • Novelist
    • This is a pay service from Ebsco. Contact Ebsco for the information to enter into these preferences
  • OCLC
    • XISBN is used to populate the editions tab on the bib record display if you have enabled FRBR. This service is free for up to 999 queries a day.
  • Open Library
    • Open Library project is an open system that you can pull cover images (and in the future additional content) from
  • Overdrive
    • This is a pay service that libraries can subscribe to for ebook content. If the library subscribes to Overdrive they can integrate that content in to Koha for free.
  • Syndetics
    • This is a pay service from Syndetics to add content for your bib records. Contact Syndetics for the information to enter into these preferences.
  • Tagging
    • Choose whether or not you want to allow patrons to add tags to records in Koha.

Acquisitions Configuration

When using acquisitions in Koha you first need to define some defaults.

Serials Configuration

When you use serials there are a few options you can set before hand.

Planning for Go-Live

Once you have all of your settings ready, you need to prepare for making your system live:

  • Decide if you need training by an outside service or if your staff can do the training themselves.
  • Make sure that there is time for your staff to play with your test system and get comfortable with it
  • If this is a migration, work with your previous company to extract data right before you go live
  • Come up with URLs for your new Koha OPAC & Staff Client
  • Make sure that if you’re hosting your own system you have a backup plan

SOPAC2 Installation


This is an installation guide for SOPAC2 and its Koha connector. It has been tested on Debian Lenny and Ubuntu Jaunty with Drupal 6.12 and Koha 3.0.x. It does not cover the installation of Koha and Drupal, only SOPAC, its dependencies and the connector.

Installation of Locum and Insurge

Locum and Insurge are the two libraries used primarily by SOPAC. They serve as a layer of abstraction to the data. Insurge manages the social aspect (tags, reviews, ratings), while Locum manages the connection to the ILS via the connector. Both libraries use a different database from that of Drupal.


There are no packages for Debian MDB2 yet, you can install it via pear:

# apt-get install php-pear
# pear install MDB2
# pear install MDB2#mysql


Download the Locum and Insurge libraries from SVN:

# cd /usr/local/lib
# svn co locum
# svn co insurge

Creation of the Database

$ mysql -u root
mysql> create database scas;
mysql> grant all privileges on scas.* to scas_user@'localhost' identified by 'scas_pass';
mysql> flush privileges;
mysql> exit

Sync DSN

This file will provide the connection information to a DB libraries:

# nano /usr/local/etc/locum_insurge_dsn.php

It should contain:

$dsn = 'mysql://scas_user:scas_pass@localhost/scas';

Installation of Insurge

If you customize the name of the database, remember to edit the sql file:

# nano /usr/local/lib/insurge/sql/scas_insurge.sql

Import Insurge:

$ mysql -u root -p < /usr/local/lib/insurge/sql/scas_insurge.sql

Configure Insurge:

# nano /usr/local/lib/insurge/config/insurge.ini

The variables in insurge.ini are empty. The default values are too long and cause MySQL errors.

Here is a sample of insurge.ini

; This is the Locum configuration file
; General configuration options for your installation of Insurge.
dsn_file = "/usr/local/etc/locum_insurge_dsn.php"
; This is where you configure your repository membership information.
; parent_server is the server name of the repository parent server you have been
; told to use.
; group_id = The group ID you have been given by your repository admin.
; These configuration points are OPTIONAL and are only necessary if you are
; participating in a repository relationship.
parent_server = ""
group_id = ""
group_key = ""

Installation of Locum

The same procedure applies to Locum

# nano /usr/local/lib/locum/sql/scas_locum.sql
# mysql < /usr/local/lib/locum/sql/scas_locum.sql
# nano /usr/local/lib/locum/sql/locum_init.sql
# mysql < /usr/local/lib/locum/sql/locum_init.sql
# nano /usr/local/lib/locum/config/locum.ini
# mkdir /usr/local/var
# mkdir /usr/local/var/log

Configure the DSN:

dsn_file = "/usr/local/etc/locum_insurge_dsn.php"

And the information for your Koha installation:

ils = "koha";
ils_version = "30x"
ils_server = "localhost"
ils_harvest_port = "80"

The rest depends on your Koha configuration.

Installation of Koha Connector

Download the Koha connector using SVN:

# cd /usr/local/lib/locum/connectors/
# svn co locum_koha_30x

Harvest Records

Now that the connector is in place, we will be able to launch harvest.php, a tool that will reap Locum DB Koha and fill the locum.

Start by configuring harvest.php:

# nano /usr/local/lib/locum/tools/harvest.php

Here are the variables you must change:

$first_record = 1;
$last_record = 30;

These are the minimum and maximum biblionumbers from your Koha install.

Then start the harvest:

# chmod +x /usr/local/lib/locum/tools/harvest.php
$ /usr/local/lib/locum/tools/harvest.php

Installation of Sphinx

Sphinx is the indexer for the database used by Locum and Insurge.


There is no Debian package for Sphinx so you’ll have to compile the source directly:

# apt-get install g++ make libmysql++-dev

Download and Compile

$ wget
$ tar zxvf sphinx-0.9.8.tar.gz
$ cd sphinx-0.9.8
$ ./configure --prefix=/usr/local/sphinx
$ make
# make install
# mkdir /usr/local/sphinx
# mkdir /usr/local/sphinx/lib
# cp api/sphinxapi.php /usr/local/sphinx/lib/
$ rm -R sphinx-0.9.8*

Creation of User and Group

Creating a Sphinx user and change the owner:

# adduser sphinx
# addgroup sphinx
# usermod -G sphinx sphinx
# mkdir /usr/local/sphinx/var/run
# chown -R sphinx.sphinx /usr/local/sphinx/var

The Sphinx daemon


# cd /etc/init.d
# wget
# chmod +x /etc/init.d/sphinx

Add Sphinx to the default boot services:

# update-rc.d sphinx defaults


Copy the configuration file supplied with the source of Sphinx before the change:

# cp /usr/local/lib/locum/sphinx/sphinx.conf /usr/local/sphinx/etc/
# sed 's/locum_db_user/scas_user/g' /usr/local/sphinx/etc/sphinx.conf > tmpfile;
mv tmpfile /usr/local/sphinx/etc/sphinx.conf
# sed 's/locum_db_pass/scas_pass/g' /usr/local/sphinx/etc/sphinx.conf > tmpfile; mv tmpfile /usr/local/sphinx/etc/sphinx.conf

And if you personalize the name of the database:

# sed 's/scas/MY_DB/g' /usr/local/sphinx/etc/sphinx.conf > tmpfile; mv tmpfile /usr/local/sphinx/etc/sphinx.conf

Indexing documents

Indexing is necessary if you want to use the search features of SOPAC.

You must first complete the Insurge table index

# chmod +x /usr/local/lib/insurge/tools/update-index.php
$ /usr/local/lib/insurge/tools/update-index.php

Then start indexing Sphinx

$ /usr/local/sphinx/bin/indexer --all

Finally, we must start the daemon:

# /etc/init.d/sphinx start

When the daemon is running, you can update the index with:

$ /usr/local/sphinx/bin/indexer --all --rotate

Installation of SOPAC2

Now to the SOPAC software itself:


Download from SVN:

$ cd /chemin/vers/drupal/sites/all/
$ mkdir modules
$ cd modules/
$ svn co sopac


In Drupal’s administration settings, activate the module. Also, enable the dependencies:

  • Profile
  • PHP Filter
  • Path

The Drupal menu should now list these entries.


Then go into the settings of SOPAC.

  • Configure the paths to the Locum and Insurge libraries
  • Choose a URL prefix SOPAC, in my “catalog”. Create a node with content like:
print sopac_search_form('both');
print theme('pages_catalog');
  • Check the Input Format “PHP Code”
  • Check Move to front page
  • In URL path settings, set the SOPAC URL prefix you have chosen.

Go to the root of Drupal, a search form will appear.

Remember to empty Drupal’s cache when something does not work.

Drupal offers a few blocks, which are not configured by default. You must specify on which page they should appear.