Book 1: For the Library IT Support Staff

"What is written without effort is, in general, read without pleasure."

-Samuel Johnson

To Start

The usual pattern for a Koha installation is the setup of a dedicated server in the library to support the installation of a server grade operating system and the necessary support software. Koha was originally designed to run with Apache running on Linux. Most sites have continued this trend. It is possible to run Koha on Microsoft's Windows server platform with appropriate ports of support tools. To prevent confusion, a separate section covers the efforts to adjust Koha for Windows. Koha should run with little or no adjustment necessary on most versions of Unix. Similarly, there are no Apache specific areas in the code, however we have little feedback on how the application will run with other HTTP daemons. Any feedback is most appreciated.

NB: All the Koha system administrators are firm believers in backing up the database on a regular schedule.

A new option with the 1.2 release of Koha

If you're not particularly interested in going through this section, a large portion of the Step by Step (below) is automated. It is a very recent addition to the Koha suite, but it should be fine for a not heavily customized installation. Try running:

 perl installer.pl


or you can follow the usual route...

Installating Koha, Step By Step

Before You Begin

To successfully use Koha you need some supporting software:

  • A webserver (It was built to work with Apache, but there is no reason it should not work with any other webserver).

  • Mysql (You could intead use postgres, or another sql based database)

  • Perl (mod_perl isnt needed but Koha should work with it).

  • Perl Modules:

    • Date::Manip

    • DBI

    • Set::Scalar

    • DBD::mysql (or whatever database system you use)

    • AuthenDBI (if you want to use Database based authentication)

    • CDK (for the telnet interface not nessecary if you plan to use the web based circulation module) also requires installation of the C CDK libraries http://www.vexus.ca/CDK.html (currently, the CDK Module has problems )



Step by Step

  1. Create a new mysql database called for example Koha

    From command line:

    mysqladmin -uroot -ppassword create Koha
    


    There is a databse installation shell script included with the Koha tarball.

  2. Set up a koha user and password in mysql

    Log in to mysql:

    mysql -uroot -ppassword
    


    To create a user called "koha" who has full administrative rights to the "Koha" database when authenticating from "localhost",

    enter the following on mysql command line:

    grant all privileges on Koha.* to koha@localhost identified by 'kohapassword';
    


    Press ENTER, and if you see no errors then enter \q to quit mysql.

  3. Create the databasetables.

    Use the mysql script to create the tables.

    mysql -uusername -ppassword Koha < koha.mysql
    


  4. Edit koha.conf

    Set the database name to what you have called your database, hostname will probably stay as localhost (unless you are installing the database on a different machine to the webserver) User and password should be changed to reflect the username and password you have chosen above.

    You can include a line called "includes= " with path to your includes folder instead of entering the path in Output.pm - see example in KohaHints.

  5. Copy koha.conf to /etc/

    The permissions on this config file should also be strict, since they contain the database password. At a minimum, the apache user needs to be able to read it, as well as any other user that runs circ.

    [I would suggest ownership of www-data.libadmins with no access to others.libadmins contain all users that use koha (If you set the owner as www-data you will need to make sure apache is running as www-data)]

  6. and update your database tables

    perl updatedatabase -I /pathtoC4
    


  7. Create directories for scripts and html documents.

    Here you need to decide where your scripts and html are going to live.

    And edit C4/Output.pm to reflect that.

    Set $path= where your includes live, for example:

    $path="/usr/local/www/koha/htdocs/includes";
    


  8. Set up your Online Public Access Catalogue (OPAC)

    Set up a webspace for the OPAC: For example: You might make /usr/local/www/opac ... and set a virtual host in apache to use that dir

    In your opac dir make a dir called htdocs, and copy everything in opac-html/ to it.

    Again in your opac dir make a dir called cgi-bin and copy all the files in opac-cgi/ that have a .pl extension to it, eg:

    cp opac-cgi/*.pl /usr/local/www/opac/cgi-bin/koha/ 
    


    Your virtual host should be set up to use these dirs, something like this:

     
             < VirtualHost opac.your.site >                         
             ServerAdmin webmaster@your.site                            
             DocumentRoot /usr/local/www/opac/htdocs                     
             ServerName opac.your.site                      
             ErrorLog logs/opac-error_log       
             TransferLog logs/opac-access_log               
                     < /VirtualHost >
    


    When finished, restart apache and point your browser at opac.your.site and it should be all go (of course - if you dont have any data in the database there won't be much to see!)



  9. Set up the intranet/librarian interface

    Create new directories and additional httpd.conf changes to Set up another webspace. Lets call it koha .

    For example:

    In the dir you have just created make an htdocs dir and a cgi-bin dir

    Copy everything in intranet-html/ to the htdocs dir

    Copy all the .pl files in intranet-cgi/ to the cgi-bin/koha dir

    Make sure your virtual host is set up to use these dirs

    Restart apache then point your browser at koha.your.site and it should work



  10. Configure security for the Librarians/Intranet Interface

    If you are using AuthenDBI to do your authentication, you will need to add some users to the users table in the koha database. And edit your apache conf file to use AuthenDBI on the intranet site.

    Otherwise, set up htaccess files in both koha/htdocs/ and koha/cgi-bin . You can use general .htaccess based security. It is important though to password protect the librarians interface because from it you can delete and add items, remove borrowers fines and generally case havoc.



Installation Alternative Options

Installing without Root

Arrange for a user called opac and set the user in the OPAC virtual host. If you do this, all cgi will be executed as (user) opac. The Virtualhost than may suexec to the user installing Koha, and koha.conf can then be written by that user, avoiding the need for the chown command, which is restricted to a superuser. Remember it is then extremely important to set PERL5LIB environment variable to point at the libraries you have installed:

 SetEnv PERL5LIB /some/path/to/modules

Installation without Virtual Hosts

Koha is designed to be installed as two separate services - each having a unique web address and folder structure (two virtual web hosts). Both services access a single SQL database which may be hosted on the same server or on a remote server. Following the steps below reconfigure koha (the intranet and opac) to run on a single, non-virual server.

NB: In the examples below, pathto = /usr/local/www

Create new /etc/koha.conf
           database=kohadb
            hostname=localhost
            user=kohadbuser
            pass=xxxxxxxx
            includes=/pathto/html/koha/includes
           


Create a general purpose web site:

/pathto/html

/pathto/cgi-bin

Create koha web installations folders:

/pathto/html/koha/includes

/pathto/html/koha/oadmin

/pathto/html/koha/opac

Create koha cgi-bin folders:

/pathto/cgi-bin/opac

/pathto/cgi-bin/koha

/pathto/cgi-bin/koha/C4

Copy koha distro opac-html\* into /pathto/koha/opac/*

Copy koha distro intranet-html\* into /pathto/koha/oadmin/*

koha distro koha\* into /pathto/cgi-bin/oadmin (including C4 directory and its contents).

Copy member.pl + seach.pl into /pathto/cgi-bin/opac

Move /pathto/koha/opac/images/* into /pathto/images/opac/*

Move /pathto/koha/oadmin/images/* into /pathto/images/oadmin/*

Rename opac *.inc files so that they all have opac-* prefix ie

rename "join-top.inc" to "opac-join-top.inc"

and rename "members-top.inc" to "opac-members-top.inc"

Move ALL includes from koha distro into /pathto/koha/includes [(It is preferable that any new includes for opac should be named using the "opac-" prefix convention (or similar)].

Example excerpts from apache httpd.conf:

           ServerName? library.example.org
            ServerPath? /usr/local/www
            DocumentRoot? /usr/local/www/html
            #
            Alias /images/ "/usr/local/www/html/images/"
            SetEnv? PERL5LIB "/usr/local/www/cgi-bin/koha"
            
            < Directory /var/www/html >
            # This is the root of general purpose website
            # NO server side includes!
            AllowOverride? None
            Options -Includes -FollowSymlinks? -Indexes
            Order Deny,Allow
            Allow From All
            < /Directory >
            
            # ======== Use Server Side Includes Here =======
            < Directory /usr/local/www/html/koha/opac >
            AllowOverride? None
            Options +Includes -FollowSymlinks? -Indexes
            AddHandler? server-parsed .html
            < /Directory>
            #
            < Directory "/usr/local/www/html/koha/oadmin">
            # 
            AllowOverride? None
            #
            # First, you must enable +Includes or +IncludesNoExec?
            # in "Options"...
            Options +Includes -FollowSymlinks? -Indexes
            #
            # Allow server-parsed content (SSI) for files 
            AddHandler? server-parsed .html
            #
            # Optional simple server based authentication....
            # Authtype Basic
            # AuthName? Koha-Online-Admin
            # AuthUserFile? /usr/local/www/ok_users/koha-users
            # AuthGroupFile? /usr/local/www/ok_groups/koha-groups
            # < Limit GET POST PUT DELETE>
            # require user koha-admin group lib-admins
            # < /Limit>
            < /Directory> 
            < /VirtualHost>