Installing Multiple Instances of Koha

From Koha Wiki

Jump to: navigation, search
Home > Documentation
Home > Documentation
Home > Documentation
Home > Documentation > Installation
Koha > Technical > Administration
Tips & Tricks > Tips & Tricks/Customising Notices and Slips > Tips & Tricks



Koha users often need to install multiple Koha instances on the same server. We explain an install schema that allows this. It relies on Apache's VirtualHost definitions and a naming schema for directories. Other methods can be explored, but this one has been reported successful and it is used in production in many places.

This guide works on Ubuntu Linux. If you need support for other operating system, several commands could need to be changed as different Linux distributions have their own configuration schemas.


Depending on your host operating system you should carefuly read the provided INSTALL.<OS> file. We will be performing a standard install. We assume that (we will be using and) you've already installed a MySQL server on the local server. We will be running the commands from root user's shell.

We also need to have koha user and group previously defined in our server.

Apache settings

First, we make sure you have the following in your /etc/apache2/ports.conf and adjust if needed:

NameVirtualHost *:80
NameVirtualHost *:8080
Listen 80
Listen 8080

Also make sure we have the mod_rewrite and mod_deflate module enabled

# a2enmod rewrite
# a2enmod deflate

Instance naming schema

Our Koha instances will be named koha_instance (in this example koha_test). This information will be used in the install process and in database creation steps.

We will set several environment variables so we can copy and paste the commands provided here. Adjust it to your Koha's instance name and database settings:

# export KOHAINSTANCE="koha_test"
# export DBHOST="localhost"
# export KOHADBUSER="kohaadmin"
# export KOHADBPASS="katikoan"

Database creation

As stated in the INSTALL file we first create our instances database following the proposed schema.

Koha on a local DB

# mysql -h $DBHOST -p -e "FLUSH PRIVILEGES"

Koha on a remote DB

If you're installing koha using a remote database you need to specify your Koha's server IP number when giving kohaadmin user the right privileges so you have to be sure you know it. If it was then we can use:

# mysql -h $DBHOST -p -e "FLUSH PRIVILEGES"

Install Koha following the schema

We now proceed with an standard install, using the values we provided for the above commands.

Note: this varies depending on the version you're trying to install. You should check for the latest stable version on Koha's download section. You should also notice that in this guide we choose some defaults configurations that could not be suitable for you so you should fine tune this for your case.

We first download and extract the sources, in a proper place:

# cd /usr/local/src/
# wget
# tar xvzf koha-latest.tar.gz

we then configure the sources (depending on which is the current version this might be different):

# cd koha-3.02.01
# perl Makefile.PL

You will then be prompted to enter your params, proceed as follows:

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

as we want a standard install, hit Enter to have the default value selected. Then you have to enter the install directory, we follow our schema so type /usr/share/koha_test and hit Enter

Base installation directory [/usr/share/koha] /usr/share/koha_test

On the next cited prompts hit Enter on each.

User account [koha]
Group [koha]
DBMS to use (Pg, mysql) [mysql]

On this one hit Enter for local database install, or type the previously used DB server IP

Database server [localhost]
DMBS [3306] 

Use the name of the database we created koha_test and hit Enter:

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

We then use the credentials we chose for the database user:

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

Zebra usage is encouraged so we follow the steps to use it, for the MARC flavour for zebra choose your's.

Install the Zebra configuration files? (no, yes) [yes] yes
MARC format for Zebra indexing (marc21, unimarc) [marc21] marc21
Primary language for Zebra indexing (en, fr) [en] en

Usage of dom mode for indexing authorities has several penalties (cite needed, or correct if wrong), choose grs1:

Authorities indexing mode (dom, grs1) [dom] grs1

Follow with the default values

Please specify Zebra database user [kohauser] 
Please specify the Zebra database password [zebrastripes]
Install the SRU configuration files? (no, yes) [yes] 
SRU Database host? [localhost]
SRU port for bibliographic data? [9998] 
SRU port for authority data? [9999]
Install the PazPar2 configuration files? [no]
You will need a Memcached server running. (no, yes) [no]
Would you like to run the database-dependent test suite? (no, yes) [no]

You will be warned if you have dependencies not met, correct them using cpan or your distro's package method. There is several info on this on the wiki.

We now perform the install process:

# make
# make install

If everything goes OK you will find you now have this directories on your server:


Adjust Virtualhost definition

Edit the koha's virtualhost definition file (we use vim here, use your favourite):

vim /etc/$KOHAINSTANCE/koha-httpd.conf

Search for the lines begining with <VirtualHost like this:


and substitute the IP number for * like this:

<VirtualHost *:80>
<VirtualHost *:8080>

Configure Apache, Zebra daemon and cronjobs

We now create some needed symbolic links for running the zebra daemon and launch it:

# export KOHAPATH=/usr/share/$KOHAINSTANCE
# ln -s $KOHAPATH/bin/ /etc/init.d/$KOHAINSTANCE-zebra-daemon
# update-rc.d $KOHAINSTANCE-zebra-daemon defaults 
# /etc/init.d/koha_test-zebra-daemon start

and tell Apache to publish our Koha:

# ln -s /etc/$KOHAINSTANCE/koha-httpd.conf /etc/apache2/sites-available/$KOHAINSTANCE
# a2ensite $KOHAINSTANCE
# /etc/init.d/apache2 reload

We now create a dummy file for putting this instance's cronjobs, with the proper environment variables set:

# echo "PERL5LIB=$KOHAPATH/lib" > /etc/cron.d/$KOHAINSTANCE
# echo "KOHAPATH=$KOHAPATH" >> /etc/cron.d/$KOHAINSTANCE
# echo "KOHA_CONF=/etc/$KOHAINSTANCE/koha-conf.xml" >> /etc/cron.d/$KOHAINSTANCE

and set a very basic cronjob that checks for updates on our registers every minute and reindexes them in zebra

# echo "1 * * * *    koha    $KOHAPATH/bin/migration_tools/ -a -b -z 2>&1 > /dev/null" >> /etc/cron.d/$KOHAINSTANCE

Ending notes

And that's all.

Personal tools