====== Koha Installation ======

====Introduction====
koha, the first open source integrated library system. Made in New Zealand by Katipo Communications Ltd. and maintained by a team of volunteers from around the globe, the Koha system is a full catalogue, opac, circulation and acquisitions system.


====Download====
   http://www.koha.org/download/index.html

====Installation and support====
   http://www.koha.org/installation/

====System requirements====
     * A webserver (It was built to work with Apache, but there is no reason it shouldnt work with any other webserver): In toetoe, we use Apache webserver.
     * Perl
     * Mysql (You could intead use postgres, or another sql based database): In toetoe, we use MySQL.
     * Required Perl Modules:
       *Date::Manip
       *DBI
       *DBD::Mysql (or whatever database system you use)
       *AuthenDBI (if you want to use Database based authentication)
       *CDK (for the telnet interface): Which in turn depends on the C CDK libraries http://www.vexus.ca/CDK.html
    * Z3950/YAZ

====What is Z3950?==== 
 http://www.loc.gov/z3950/agency/

====Z39.50 Setup====
Finally, you will need to start your Z39.50 daemon so you can do Z39.50 searches for catalog records.
<code>  [[root@localhost|koha-2.0.0]]# cd /usr/local/koha/intranet/scripts/z3950daemon
 [[root@localhost|z3950daemon]]# ./z3950-daemon-launch.sh</code> 

This script starts your Z39.50 daemon.  You will need to restart this daemon manually every time your reboot your system, or add it to the daemons that are automatically started at boot time by editing your etc/rc.local file (as root) and adding this line at the end of the file:
<code>  $ /usr/local/koha/intranet/scripts/z3950daemon/z3950-daemon-launch.sh</code> 

The Z39.50 server at the Library of Congress is already set up as a search target by default in Koha.  You can use your Koha System Parameters page to add and delete details about other Z39.50 targets you wish to search.  Then when you add a new bibliographic record to Koha, you can type in an ISBN or a title and click on "Z39.50 Search."  Koha will open a new window reporting on the progress of the search and returning any records found, which can then be automatically loaded into the cataloging template for editing and saving into your Koha database.

====Technical issues====
MySQL: With mySQL, the system setting are as follows:
<code>  /etc/mysql/my.cnf: The global mysql configuration file.
 $Header: /var/cvsroot/gentoo-x86/dev-db/mysql/files/my.cnf-4.0.14-r1,v 1.2 2004/07/18 02:47:43 dragonheart Exp $
 
 This file can be simultaneously placed in three places:
 1./etc/mysql/my.cnf to set global options.
 2./var/lib/mysql/my.cnf to set server-specific options.
 3.~/.my.cnf to set user-specific options.</code> 
 
One can use all long options that the program supports. Run the program with --help to get a list of them. The following values assume you have at least 32M RAM!
<code> 
 [[client]]
 #password	= my_password
 port		= 3306
 socket		= /var/run/mysqld/mysqld.sock 

 [[safe_mysqld]]
 err-log		= /var/log/mysql/mysql.err 
 [[mysqld]]
 skip-innodb
 user		= mysql
 pid-file	= /var/run/mysqld/mysqld.pid
 socket		= /var/run/mysqld/mysqld.sock
 log-error	= /var/log/mysql/mysqld.err
</code> 
Therefore, whenever run mySQL server the parameters set up will always use the default. In order to run Koha with MySQL, the following setting needs to be used:
<code>  [[client]]
 --socket=/tmp/mysql.sock
 [[safe_mysqld]]
 err-log		= /home/chi/local/mysql/mysql.err</code> 

<code>  [[mysqld]]
 skip-innodb
 user		= mysql
 pid-file	= /home/chi/local/mysql/mysqld.pid
 socket		= /tmp/mysql.sock
 log-error	= /home/chi/local/mysql/mysqld.err</code> 
 
Also, the my.conf file should be stored ./.my.conf in order to take effect as a user-specific options.

====Modifying the source code====
<code>  * /home/chi/src/kohaXXX/installer.pl
 #my $domainname = `hostname`; # Note: must not have any arguments (portability)
 my $domainname = "toetoe.cs.waikato.ac.nz";
 #  elsif (open(INPUT, "</etc/hostname")) {
    elsif (open(INOUT, "<toetoe")){
 #my $etcdir = $ENV{etcdir}||'/etc';
 my $etcdir = $ENV{etcdir}||'/home/chi/local';</code> 

The above changes are for the issues of permission!

  */home/chi/src/kohaXXX/modules/C4/Context.pm
<code>  Add mysql_socket=/tmp/mysql.sock into the following line!
 return DBI->connect("DBI:$db_driver:$db_name:$db_host:mysql_socket=/tmp/mysql.sock", $db_user, $db_passwd);</code> 

Once install, It appears that the system would make a copy of C4/ to /home/chi/local/perl_mod/lib/perl5/site_perl/5.8.2/i686-linux/C4. Therefore, don't foget to change the code of i686-linux/C4/Context.pm as well.

some relevant information about DBI can be seen from the below website:
<code>  *http://www.bitmechanic.com/mail-archives/mysql/current/1851.html
 Example:
 $dbh = DBI->connect("DBI:mysql:$opt_db:$opt_host:port=$opt_port:mysql_socket=$opt_mysql_socket", $opt_user,$opt_password, { PrintError => 0})  || die $DBI::errstr;</code> 

====Install====
Follow the instruction from the one-line document: Automated configuration:
<code>  *http://www.koha.org/installation/manual/book1_library_it_support.html#TO_START</code> 

====Setting up the PORT for the Koha====
In Koha, the system provide two interfaces which are OPAC (Online Public Access Catalogue) and INTRANET: The suggestion is to set up these two interfaces into different ports (in toetoe, OPAC: Port 8000 INTRANET: port 8200).

Remember: to modify /home/chi/local/apache_1.3.31/conf/httpd.conf.

First of all, include the line: Include /home/chi/local/koha-httpd.conf
Secondly, modify Listen to both 8000 and 8200.

Restart Apache server in order to take effect.

====Problem issues====
When the installation was failed, in the database, the user details will still be created into mysql:db table and mysql:user. You need to delete it manually.

For example:
<code>  mysql> use mysql;
 mysql> delete from db where Db="Koha";
 mysql> delete from user where user="kohaAdmin";</code> 

When I try to run web browser, it always comes out the below error messages:
<code>  # Error: Can't Locate HTML/Template.pm.. in the koha system.
 # Error: To the web-end, 500 Internal Server error....</code> 

Obviously, the koha system can't not trace up the directory of the perl_mod. I tried to modify the httpd.conf, but it is still not working. So the temporary solution, is copy all the required perl modules into /home/chi/local/koha/intranet/modules

==== Starting Koha====
  * Step 1: Start MySQL
<code>  $ cd /home/chi/local/mysql
 $ bin/safe_mysql --user=root --socket=/tmp/mysql.sock &</code> 

  *Step 2: Start Apache:
<code>  $ cd /home/chi/local/apache_1.3.31
 $ bin/apachetl start</code> 

  *Step 3: Web browser
<code>  http://toetoe.cs.waikato.ac.nz:8200/ redirect to http://toetoe.cs.waikato.ac.nz:8200/cgi-bin/koha/mainpage.pl</code> 

  * A demo Koha can be found:
<code>http://koha.liblime.com/cgi-bin/koha/mainpage.pl 
user: circ
password: liblime
</code>

  * Koha will run with MYSQL server set up in the /tmp/mysql.sock socket.In /home/chi/bin, there is a wiki.start script (I was running mysql socket in /tmp/9306.sock for my personal wiki), the setting can be changed here to run koha.