Install Koha on Ubuntu — Part 4: Koha

This is part 4 of 6 in a tuto­r­ial series on installing Koha 3.0 on Ubuntu 8.10.

The pre­ced­ing arti­cles have laid the ground­work by installing and con­fig­ur­ing Linux, and then by installing all the under­ly­ing soft­ware that Koha requires.

This arti­cle covers—at last!—the instal­la­tion of Koha itself.

If you plan to put Koha into pro­duc­tion for real-world Library use there are many other things you need to con­sider. The final arti­cle in the series, Going Live, dis­cusses this further.

Con­fig­ure Linux Permissions

Using Web­min (or another method if you pre­fer) cre­ate a user named “koha” and add it to a group named “koha”:

1. Sys­tem > Users and Groups
2. “Cre­ate new user” link (above the “Delete/Disable/Enable Selected Users” button)
3. User­name: koha
4. Real name: Koha User
5. Pass­word (Nor­mal Pass­word): {enter a koha admin pass­word here}
6. Group Mem­ber­ship > Pri­mary Group > New Group: koha
7. Cre­ate

Con­fig­ure MySQL

These instruc­tions assume you’re using Web­min to con­fig­ure MySQL. If you’re more com­fort­able with another tool or the shell prompt, that’s fine too.

Before you can admin­is­ter MySQL through Web­min it will prompt you for the MySQL admin­is­tra­tive login. The user should be “root”, and the pass­word is the one you cre­ated ear­lier when con­fig­ur­ing LAMP.

First cre­ate a new Koha admin­is­tra­tive user with all per­mis­sions on your server, local­host: Servers > MySQL Data­base Server > User Per­mis­sions (under “Global Options”) > Cre­ate new user (at the top of the page). Fill in the prompts as follows:

Username: { choose a koha administrator name — one word }
Password: { choose a koha administrator password}
Hosts: localhost
Permissions: all permissions
[Create]

Next cre­ate a data­base for Koha to use: Servers > MySQL Data­base Server > Cre­ate a New Data­base (under “MySQL Data­bases”). Leave all options as they default except:

Database name: koha
[Create]

Finally, give your Koha admin­is­tra­tive user full per­mis­sions for the “koha” data­base: Servers > MySQL Data­base Server > Data­base Per­mis­sions (under “Global Options”) > Cre­ate New Data­base Per­mis­sions. Fill in the form as follows:

Databases: Selected (koha)
Username: { enter the koha administrator name from above }
Hosts: from host permissions
Permissions: all permissions

Install Koha

At last!

Ver­ify SAX Parser

Con­firm your sys­tem is using the cor­rect SAX parser (XML::LibXML). After run­ning the fol­low­ing com­mand you should see some­thing like “XML::LibXML::SAX::Parser=HASH(0x81f0a74)”.

cd /build/koha-3.00.00/misc
./sax_parser_print.pl

If you don’t have the right parser your Koha sys­tem will have prob­lems with extended char­ac­ters (e.g., accented char­ac­ters). To cor­rect this prob­lem you’ll need to edit the ParserDetails.ini file. First find the file:

locate ParserDetails.ini

This will prob­a­bly report two files by that name, but one of them should sim­ply be a sym­bolic link to the other in which case you can edit either one. So for exam­ple, if your file is at /etc/perl/XML/SAX/ParserDetails.ini, you would edit it like this:

gedit /etc/perl/XML/SAX/ParserDetails.ini

Impor­tant! The above com­mand might not be the right one for your sys­tem. See the expla­na­tion below.

While the above file loca­tion will be cor­rect for some Ubuntu instal­la­tions, it isn’t the right loca­tion for all of them. That’s why we did the “locate ParserDetails.ini” com­mand above. Use the results of that com­mand to fig­ure out the loca­tion of the ParserDetails.ini file on your sys­tem. If you find mul­ti­ple copies of the file, con­sider edit­ing both of them.

The file should have one or more sec­tions that look some­thing like “[XML::LibXML::SAX::Parser]” fol­lowed by one or more lines of set­tings. To use the right parser, move the “[XML::LibXML::SAX::Parser]” sec­tion (includ­ing the set­tings that fol­low it) to the bot­tom of the file, then retest:

./sax_parser_print.pl

Install Koha Files

First we need to make the Koha application.

The perl Makefile.pl com­mand will run for sev­eral min­utes, ask you sev­eral ques­tions, and gen­er­ate e-reams of diag­nos­tic text. In gen­eral you’ll do well to accept the default answers.

When prompted “Please spec­ify the name of the user that owns the data­base to be used by Koha”, pro­vide login infor­ma­tion for the koha MySQL user you cre­ated ear­lier on this page. The make test and make install com­mands will also run for sev­eral min­utes but you won’t need to answer any prompts.

sudo su
cd /build/koha-3.00.00
perl Makefile.PL
make
make test
make install

Next we need to con­fig­ure Apache to rec­og­nize Koha as a valid web­site. To do this, the default Apache con­fig­u­ra­tion direc­tory needs to have a sym­bolic link to the Koha Apache con­fig­u­ra­tion file, koha-httpd.conf. Cre­ate the sym­bolic link like this:

ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha

Next we need to enable a required Apache mod­ule (the rewrite mod­ule) and then enable the Koha site.

a2enmod rewrite
a2ensite koha

We’re almost done! By default Koha uses port 8080 for its admin­is­tra­tive inter­face, the web site library staff will use. We need to tell Apache to accept web page requests on port 8080 in addi­tion to the default port, 80. To do this edit the port con­fig­u­ra­tion file:

gedit /etc/apache2/ports.conf

Add this line then save and exit.

Listen 8080

Finally, restart Apache to put the new con­fig­u­ra­tion set­tings into effect:

/etc/init.d/apache2 restart

Next Sec­tion…

Part 5: Test­ing