Installing Multiple Instances of Koha
WARNING! This page is obsolete.
This page is no longer correct and exists for historical reasons only.
Introduction
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.
Prerequisites
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 "CREATE DATABASE $KOHAINSTANCE"
# mysql -h $DBHOST -p -e "GRANT ALL PRIVILEGES ON $KOHAINSTANCE.* TO '$KOHADBUSER'@'localhost' IDENTIFIED BY '$KOHADBPASS'"
# 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 192.168.0.2 then we can use:
# export MYIPADDRESS=192.168.0.2
# mysql -h $DBHOST -p -e "CREATE DATABASE $KOHAINSTANCE"
# mysql -h $DBHOST -p -e "GRANT ALL PRIVILEGES ON $KOHAINSTANCE.* TO '$KOHADBUSER'@'$MYIPADDRESS' IDENTIFIED BY '$KOHADBPASS'"
# 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 http://download.koha-community.org/koha-latest.tar.gz
# 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:
/etc/koha_test
/usr/share/koha_test
/var/lib/koha_test
/var/log/koha_test
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:
<VirtualHost 127.0.0.1:80>
...
<VirtualHost 127.0.0.1:8080>
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/koha-zebra-ctl.sh /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/rebuild_zebra.pl -a -b -z 2>&1 > /dev/null" >> /etc/cron.d/$KOHAINSTANCE
Ending notes
And that's all.