"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. 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, especially before upgrades to existing Koha installations.
The preferred method of Koha installation for anyone running a Unix operating system and a machine explicity for Koha is to run the installation script:
perl -Imodules installer.pl |
which can be found with the tarball.
It is possible to install Koha manually, however this procedure is recommended for very experienced admins only.
To do so:
Make directory in tmp called Koha ( mkdir /tmp/Koha )
Make sure to install the following packages: libexpect-perl
Download the following files, from the following locations:
Bundle-KohaSupport-0.08.tar.gz from http://www.cpan.org/, Locate by searching for Koha
Net-Z3950-0.32.tar.gz [Net::Z3950] from http://www.cpan.org, Locate by searching for 3950
yaz-2.0.tar.gz from http://www.indexdata.dk/yaz/ (Specific instructions: right-hand menu/download/sources)
Unpack all sources into reasonably named directories.
Install yaz: Go into yaz-2.0, until you see the file README. Installation instructions:
$ ./configure $ make $ su PASSWORD: XXXX # make install # exit $ |
Install the Koha Bundle
$ cd /tmp/Koha/Bundle-KohaSupport-0.08 $ perl Makefile.PL $ make $ su PASSWORD: XXXX # make install # exit $ |
Install Net::Z3950. Use one of the two following scripts:
$ su PASSWORD: XXXX # perl -MCPAN -e 'install Net::Z3950' |
$ cd /tmp/Koha/Net-Z3950-0.32 $ perl Makefile.PL $ make $ make test $ su PASSWORD: XXXX # make install # exit |
Get your MySQL server running - check the MySQL website for more assistance.
Get your Apache server running - chances are that your distribution of Linux includes this and has it running already.
Start the Koha Install: [note, this is a rough outline of the steps necessary!]
Things to know:
server's domain name and system configuration directory (normally /etc - This should be an absolute path; a trailing / is not required.)
PAT FIXME: Should they create a koha.conf here, or where? Could you stick an example of a current one in appropriate place?
Select a virtual server name, port for the OPAC (catalog), and port for the intranet (librarian's interface)
add the appropriate entries to the Apache Virtual Host setup. (see enclosed)
<VirtualHost _default_:*> ServerAdmin webmaster@dummy-opac DocumentRoot /usr/www/opac/htdocs ScriptAlias /cgi-bin/ /usr/www/opac/cgi-bin/ ServerName opac ErrorLog logs/opac-error_log CustomLog logs/opac-access_log common </VirtualHost> |
set Serveradmin, Servername, DocumentRoot, ScriptAlias with associated (below) info in httpd.conf
<Directory "PATHofSOMEsort"> AllowOverride None Options None Order allow,deny Allow from all </Directory> |
Place the appropriate koha files in the appropriate directories (/usr/local/koha usually, with subdirs OPAC and INTRANET)
Load the MySQL configuration [PAT FIXME: what's the command/file for this now???] NOTE: koha.conf must exist by this point.
Restart apache.
To install Koha without access to superuser/root/sysadmin level privileges, ask your system administrator to arrange for a user called opac and then set the user in the OPAC virtual host. This will permit all of the cgi scripts to be executed as 'user' opac. The Virtualhost then 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. 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> |
Note: You will also need to change the include files to reflect the new "root" directory -- if you don't do this, everything will work until you click on a section button at the top of a page.