Installing Multiple Instances of Koha

== 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.
Category:Documentation
Category:Installation
Category:Tips_&_Tricks
Category:Documentation
Category:Installation
Category:Tips_&_Tricks