"What is written without effort is, in general, read without pleasure."
-Samuel Johnson
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...
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 )
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.
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.
Create the databasetables.
Use the mysql script to create the tables.
mysql -uusername -ppassword Koha < koha.mysql |
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.
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)]
and update your database tables
perl updatedatabase -I /pathtoC4 |
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"; |
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!)
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
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.
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 |
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> |