Bug 17356 - update README

[koha.git] / INSTALL.opensuse

= Installation Guide for Installing Koha 3.0.0 on openSUSE 11.3 =

Original version for openSUSE 11.0 created by Ricardo Dias Marques - koha@ricmarques.net
Version for openSUSE 11.3 adapted by Freek de Kruijf - freek -at- opensuse -dot- org

No liability for the contents of this document can be accepted.

Feedback/bug reports: Koha Developer's List:

http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel

This document last modified: 20 Mar 2012

== Installation Instructions ==

This document was prepared in order to help you discover (or test) Koha (Integrated Library System).

The installation of Linux system described below is a basic, it is not designed for a production server (e.g., security, load balancing ... are not described).

This document describes the different stages of installing the software Koha 3 on the openSUSE 11.3 Linux distribution in a "new" computer, the author uses a VirtualBox virtual machine, that is, a virtual computer that will have its virtual hard disk contents COMPLETELY ERASED to install openSUSE and Koha!

In this example, the virtual machine uses a bridged network connection, which mimics a separate computer in the local network, it's assumed that your server gets an IP address by DHCP that later will be changed to 192.168.1.16.

You'll have to change this to the real IP address that your machine should get (or use DHCP, if that's the case).

This tutorial assumes a Koha installation that does NOT use Zebra ("Zebra is a high-performance, general-purpose structured text indexing and retrieval engine" - http://www.indexdata.dk/zebra/). Additional steps would be required to set up Zebra for Koha, however it will be installed.

=== LINUX System Installation ===

Download openSUSE 11.3 DVD from [http://software.opensuse.org/ here].

Place the DVD in the drive and restart the machine. In the case of a virtualmachine the iso image is still on the disc and you connect it as a DVD to the virtual machine.

After the "Welcome" screen, you'll get a First menu, with the following options:

----
Boot from Hard Disk

Installation

Repair Installed System

Rescue System

Firmware Test

Memory Test
----

You may want to change the screen size to 1024 x 768 by pressing F3.
Choose "Installation" (second command)

==== "Initializing" screen ====

(Dialog box appears saying "Probing Mouse")

==== "Welcome" screen ====

You'll see two Dropdown Lists: "Language" and "Keyboard Layout"

This depends of your place and preference, naturally.
I live in The Netherlands, and we use the English (US) Keyboard Layout but I prefer an Operating System in English.
So I leave the default option selected for "Language"  and "Keyboard Layout" to (English (US)).

Check the "I Agree to the License Terms" checkbox (under the "License Agreement" textbox).

Click the "Next" button.

==== "System Probing" screen ====

[just watch it...]

==== "Installation Mode" screen ====

Leave "New Installation" radio button checked

I prefer not to have the "Automatic Configuration" so this option is unchecked.
It gives you the possibility to specify the name of the system and the network setup.

Click the "Next" button

==== "Initializing" screen ====

[just watch it...]

==== "Clock and Time Zone" screen ====

I do this work in Yemen, so I select the following options:

"Region" listbox: click on "Asia"

"Time Zone" listbox: click on "Aden"

I leave the "Hardware Clock Set To UTC" checkbox checked.

Click the "Next" button

==== "Desktop Selection" screen ====

You should see three radio buttons: "GNOME Desktop", "KDE Desktop" and "Other".

Click on the "Other" radio button.

Four radio buttons should become visible then:

"XFCE Desktop"

"LXDE Desktop"

"Minimal X Window"

"Minimal Server Selection (Text Mode)"

click on this last "Minimal Server Selection (Text Mode)" radio button.

Click the "Next" button

==== "Suggested Partitioning" screen ====

Partitioning choices are really up to you. In this example, I started with a 8 GB virtual disc and I will create a 1000 MB swap partition and the rest is the root "/" partition.

So, to do this I click on the "Create Partition Setup..." button.

===== "Preparing Hard Disk: Step 1" screen =====

I click on the first radio button:
"1: 1.IDE 8.0 GB,/dev/sda"

I click the "Next" button

===== "Preparing Hard Disk: Step 2" screen =====

I uncheck the "Propose separate Home Partition" checkbox.

I click the "Next" button.

This takes me back to the Suggested Partitioning screen.

===== "Suggested Partitioning" screen =====

In my case, I now have this:

- Create swap volume /dev/sda1 (1004.06 MB)

- Create root volume /dev/sda2 (7.02 GB) with ext4

I click the "Next" button.

==== "Create New User" screen ====

I use this screen to create a regular user.

User's full name: Your Full name (e.g: John Smith)

Username: Your preferred username (e.g.: jsmith)

Password:

Confirm Password:

I uncheck the "Use this password for System Administrator" checkbox.

I check the "Receive System Mail"

I uncheck the "Automatic Login" checkbox.

I click the "Next" button (you may be "nagged" with a dialog box by the YAST2 installer warning that you selected a password that it considers to be too simple. Click "Yes" to keep the password you chose, or "No" to change it).

==== Password for the System Administrator "root" screen ====

Enter your password (in the "Password for root User" text box) and repeat it (in the "Confirm Password" text box).

Click the "Next" button to proceed to the "Installation Settings" screen.

==== "Installation Settings" screen ====

Click on the "Software" link

==== "Software Selection and System Tasks" screen ====

Scroll down the listbox (that begins with the "Base Technologies" group) until you find the "Server Functions" group.

In that "Server Functions" group click on the "Web and LAMP Server" checkbox (to check it)

Click on the "OK" button to return to "Installation Settings"

==== "Installation Settings" screen ====

Click on the "Install" button (placed in the same place where usually appear the "Accept" or "Next" button).

You should see a "Confirm Installation" dialog box. Click on the "Install" button of that dialog box.

==== "Preparing Your Hard Disk" screen ====

[just watch it...]

==== "Deploying Installation Images" screen ====

[just watch it... ]

==== "Package Installation" screen ====

[just watch it... or click on the "Details" tab if you want to see what packages are being installed.]

==== "Finishing Basic Installation" screen ====

[just watch it... ]

After some time you'll see a dialog box warning that the system will reboot in 10 seconds.

==== After reboot ====

Leave "Boot from Hard Disk" selected and press ENTER

You'll have to wait a while (or press ESC to see what the operating system is "doing"). After some moments, you'll be taken to the "Yast2 - installation @ Linux" screen (a text installer).

On the screen you will see Hostname and Domain Name with a textbox below.
The cursor is in the textbox below Hostname.
Press the Backspace to delete the name there and insert the name of your system, e.g. koha-server.
Pres Tab and Backspace to delete "site" and enter the domain name, e.g. "univ.org".
Press Tab go to Change Hostname via DHCP en press Space to remove the "x".
Leave the "x" in Assign Hostname to Loopback IP.
Press <Alt>+N to activate "Next". Now you enter:

==== Network Configuration ====

Press ALT+C to Change Network Settings. Use the Arrow Keys to Highlight "Firewall" and press RETURN.
Proceed to Firewall and press RETURN. Go to "Allowed Services" and press RETURN. Press TAB several times to highlight "HTTP Server".
Press ALT+A to add HTTP Server to the list. Press ALT+S to choose the next Service to Allow.
Press the Down Arrow and a drop down box will appear and press the Down Arrow several times to select Secure Shell Server and press RETURN.
Press ALT+A to Add.
We also need port 8080 for the management of Koha to be open, so press ALT+D to activate (Advanced...).
Press ALT+T to go to TCP Ports and enter 8080 in the textbox.
Pressing Alt+O for OK, brings you back to the Firewall Configuration.
Pressing Alt+O for OK, brings you back to Network Configuration, but now you see the SSH port is open, the 8080 port is not shown.
Press Alt+N for Next, which brings you to: Saving Network Configuration and finally to:

==== Test Internet Connection ====

Press RETURN to activate Next and do the test.
If all is well you should see "Test Result: Success".
Press RETURN to activate Next.
Now the meta data of some repositories will be downloaded and the next screen will appear:

==== Online Update ====

Here you can choose to do an online update or not.
Press RETURN to activate Next and the update will be done.
In my case the update even replaced the kernel. Press ALT+A to Accept the update.
After that you press RETURN to activate Next.
A warning may appear saying that the system will reboot.

You will see the first screen of booting of the DVD again, but again you choose Boot from Hard Disk, which will also happen when you do not do anything.

After that you will see the normal system boot screen and you do not need to do anything, but you may press RETURN to speed up the start of booting from the disc.
In my case, after booting, the installtion went on and showed a screen of the YaST2 Package Manager showing the Release Notes.
Press RETURN to continue.
Now a screen asking about Hardware Configuration appeared. Press RETURN to continue.

Next a screen appears showing Installation Completed.
Press RETURN to continue and you will see the startup log messages and at the end the following:

|--------------------
Welcome to openSUSE 11.3 "Teal" - Kernel 2.6.34.7-0.3-desktop (tty1)

koha-server login:
|--------------------

You may now login with your "root" user.

==== Changing the Hostname and Domain Name ====


Maybe you want to change the hostname, domain name and switch from DHCP to a Static IP address.
Changing the hostname and domain name will not be shown here, because we assume that was done according to your whishes during installation.

This is how you can do it. You give the command yast (the setup tool) on the command prompt:
|--------------------
koha-server:~ # yast
|--------------------

Yast should appear.

On the listbox of the left hand side select "Network Devices" (press TAB to turn focus on that listbox, and press the down arrow key several times to reach it).
Then, on the listbox of the right hand side, select "Network Settings" (you'll have again to press TAB to turn focus on that listbox, and press the down arrow key several times to reach it).

Press the ENTER key.

==== "Initializing Network Configuration" screen ====

[just watch it...]

==== "Network Settings" screen ====

I want to disable IPv6, so I first go to the "Global Options" section (by pushing the key combination ALT+G to press the "G" letter in Global Options that is highlighted).
In the next screen, I push ALT+E to uncheck the "Enable IPv6" checkbox.
I'll get a dialog box with a Warning saying that "To apply this change a reboot is needed.".
I just press ENTER on that dialog box, but I do NOT reboot (at least not yet).

Then I press Alt+V to go to the "Overview" (still in "Network Settings").
Then I press ALT+I to "Edit" the information for this Network Card.

==== "Network Card Setup" screen ====

I check the "Statically assigned IP Address" checkbox, and enter the following info for "IP Address", "Subnet Mask" and "Hostname" (you should use the values defined by your network administrator):

IP Address: 192.168.1.16
Subnet Mask: 255.255.255.0
Hostname: koha-server.univ.org

Then I press ALT+N to click the "Next" button. After a few seconds, I will be taken again to the "Network Settings" screen.

==== "Network Settings" screen ====

I press ALT+S to go to the "Hostname/DNS" screen.

Press ALT+I and the Arrow Key to choose "Only Custom Policy" by pressing Enter, press Tab to choose "Custom Policy Rule" and select "STATIC".
Enter the IP Address of the Domain Name Server in the "Name Server 1" text box:

Name Server 1: 192.168.1.254

Then I press ALT+U to go to the "Routing" configuration.

==== "Routing" screen ====

In the "Default Gateway" text box, I enter the IP Address of my Default Gateway:

Default Gateway: 192.168.1.254

Then I press ALT+O for OK to Finish

==== "Saving Network Configuration" screen ====

[just watch it...]

After a few seconds, you should be taken back to the "YaST2 Control Center" screen.
Press ALT+Q to Quit YaST2.

==== Making the ssh-daemon to start at system start ====

We need a ssh-daemon that does not accept Environment parameters from the remote user.
So we have to disable accepting these.
For this you use vim to change the config file of sshd.

|--------------------
# cp /etc/ssh/sshd_config /etc/ssh/sshd_config.ORIG
# vi /etc/ssh/sshd_config
|--------------------

Find the lines starting with AcceptEnv and insert a # in front of these, There are three lines.
Afterwards these lines will look like:
|--------------------
#AcceptEnv LANG LC_CTYPE LC_NUMERIC LC_TIME LC_COLLATE LC_MONETARY LC_MESSAGES
#AcceptEnv LC_PAPER LC_NAME LC_ADDRESS LC_TELEPHONE LC_MEASUREMENT
#AcceptEnv LC_IDENTIFICATION LC_ALL
|--------------------

In order to make the ssh-daemon start at system boot, you have to enable this by giving:
|--------------------
# chkconfig sshd on
|--------------------

You can check the status with the command "chkconfig -l sshd".
The output should look like this:
|--------------------
# sshd                      0:off  1:off  2:off  3:on   4:off  5:on   6:off
|--------------------

Also you need to start the sshd service in order to generate the security keypair for sshd.
|--------------------
# service sshd start
|--------------------

This time seems to be a good time to reboot your server:
|--------------------
# reboot
|--------------------
After rebooting the machine, if you wish, you may go to another machine and connect to your newly created server using a SSH (Secure Shell) client. In Windows, I like to use putty to do ssh sessions to my Linux servers.

=== Configure Software Repositories ===

After the system has rebooted, log in as root.

Later on, you will need to add some software packages from the openSUSE 11 Distribution.
Some of those packages are NOT available in the openSUSE 11.3 DVD (libyaz-devel is one of those packages).
However we already added these repositories to the system after configuring the network.
In case you did not have a network setup at that time, it is now time to setup these repositories, but you can skip this if this has been done already.

First, run the yast command in the Linux command line (shell):

|--------------------
# yast
|--------------------

Inside yast, select Software -> Software Repositories

==== "Configured Software Repositories" screen ====

When on this screen, you already see a table that has:

* as configured repositories (in the "Name" column)
** "Updates for openSUSE 11.3 11.3-1.82"
** "openSUSE-11.3 11.3-1.82"
** "openSUSE-11.3-Debug"
** "openSUSE-11.3-Non-Oss" "openSUSE-11.3-Oss" ...
* at least the following repositories have an "x" in the "Enabled" column
** "Updates for openSUSE 11.3 11.3-1.82"
** "openSUSE-11.3-Oss"
* you still have to add the folowing repositiory to this list
** "openSUSE BuildService - devel:languages:perl"
Press ALT+A to Add Repositories.

==== "Media type" screen ====

Select Community Repositories by pressing ALT+I and apply Next (press ALT+X).

You will see a message that data will be downloaded.
After that you will get a list of Repositories and the above mentioned, but not yet available, will be in this list.
Select the one you need by using the Arrow Keys and press Space to select (an x will appear in front of the Repository).
After that apply OK. You may see some activity and you may get asked to import GnuPG keys, just do so.

You may see the following screen.

==== "License Agreement" screen ====

Check the "Yes, I Agree to the License Agreement" radio button.

Click on the "Next" button to return to the "Configured Software Repositories" screen.

==== "Configured Software Repositories" screen ====

You should see now the "openSUSE 11.3-Oss" listed as an entry.
You can Disable "openSUSE-11.3-Source" and its Autorefresh, if present.

Click on the "OK" button.

When you get sent back to the "Yast Control Center" click on the "Quit" button (to return to the shell).

=== Install some useful / necessary programs ===

By this time, you have to install some of the programs which are regularly used, by using zypper (the command line mode packet manager):

To install locate, ncftp (command-line ftp client), make and gcc you give the following command:
|--------------------
# zypper install findutils-locate ncftp make gcc
|--------------------
Zypper reports that it will install 18 packages; confirm with RETURN.

== Download Koha ==

|--------------------
# wget http://download.koha-community.org/koha-3.00.00.tar.gz
|--------------------
You will receive 49,266,888 bytes.

== Extract Koha ==

|--------------------
# tar -xzvf koha-3.00.00.tar.gz
|--------------------

== Set up Locale for root user ==

If you run the locale command, you'll probably get this output:
|--------------------
# locale
LANG=POSIX
LC_CTYPE=en_US.UTF-8
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_COLLATE="POSIX"
LC_MONETARY="POSIX"
LC_MESSAGES="POSIX"
LC_PAPER="POSIX"
LC_NAME="POSIX"
LC_ADDRESS="POSIX"
LC_TELEPHONE="POSIX"
LC_MEASUREMENT="POSIX"
LC_IDENTIFICATION="POSIX"
LC_ALL=
|--------------------

We want to have en_US.UTF-8 in all LC_* variables. So, we'll do the following:
|--------------------
# yast
|--------------------
System -> Language

The "Languages" screen should appear.

In the first section (Primary Language Settings):

Leave "English (US)" selected as the option for Primary Language

Click on the "Details..." link

Change the Locale Settings for user root from the default option ("ctype Only") to "Yes"

Make sure the "Use UTF-8 Encoding" checkbox is checked (it should already be).

Leave the "Detailed Locale Setting" en_US selected

Click on the OK button to return to the "Languages" screen

Click on the "OK" button.

When you get back to the "Yast2 Control Center" screen, click on the "Quit" button

== Putty configuration to use Unicode (UTF-8 encoding) ==

If you use Putty, set up Putty to use UTF-8 encoding.
To do this, click on the upper left corner of the PuTTy window, to expand the menu.
Scrol down until you find the "Change Settings..." command and click on it.

This should open the "PuTTy Reconfiguration" screen. Here expand the "Window" category and click on "Translation"

When you do this, you'll see that the "Received data assumed to be in which character set" dropdown list probably reads:

"ISO-8859-1:1998 (Latin-1, West Europe)

change it to: "UTF-8"

Click on the "Apply" button

Now, it's a good time to SAVE this PuTTy session.
To do this, click again on the upper left corner of the PuTTy window, to expand the menu, and click on the "Change Settings..." command like you did before.

This should open the "PuTTy Reconfiguration" screen. Go to the right hand side of that screen and type a name in the "Saved Sessions" textbox (e.g: koha).
Then click on the "Save" button and, after doing that, click on the "Apply" button.

IMPORTANT!!! Now it's the time to EXIT the login shell, by typing the exit command:
|--------------------
# exit
|--------------------

Now you'll reopen PuTTy, but when you do that, open the Saved Session that you have created in order to use the "UTF-8" configuration you have done.

You may not need to do the above after the change, made earlier, in /etc/ssh/sshd_config. Check it and if so you can modify this wiki page.

After logging in again with the root user, type the locale command again. Now it should read like the following:

|--------------------
# locale
LANG=en_US.UTF-8
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=
|--------------------

== Apache configuration (for UTF-8) ==

Create a file called /etc/apache2/httpd.conf.local with vim (or your preferred text editor):
|--------------------
myhost:~ # vim /etc/apache2/httpd.conf.local
|--------------------
Add this line:
|--------------------
AddDefaultCharset UTF-8
|--------------------

== Configure Apache to start at boot time and start the service ==
|--------------------
# chkconfig apache2 on

# service apache2 start
Starting httpd2 (prefork)                                            done
|--------------------

Go to a browser and type:

http://192.168.1.16

You should see a page that reads:

"It works!"

== MySQL configuration ==

1 - Configure MySQL to start at boot time and start the service:
|--------------------
# chkconfig mysql on

# service mysql start
|--------------------
The system will issue a warning that '--skip-locking' is deprecated, but for now we accept that.

2 - Change the password for the "root" user of MySQL:
|--------------------
# /usr/bin/mysqladmin -u root password 'chosenpassword'
|--------------------
After starting MySQL also it is recommended to give the command:
<tt> # /usr/bin/mysqladmin -u root -h koha-server.univ.org password 'chosenpassword'</tt>
However this gives an error message. This is left for the more advanced MySQL administrator.

3 - Check the encoding variables of MySQL

To check the encoding variables of MySQL, will type the show variables like 'char%'; command in a mysql prompt:
|--------------------
# mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 7
Server version: 5.1.46-log SUSE MySQL RPM

Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
This software comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to modify and redistribute it under the GPL v2 license

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> show variables like 'char%';
+--------------------------+----------------------------+
| Variable_name            | Value                      |
+--------------------------+----------------------------+
| character_set_client     | utf8                       |
| character_set_connection | utf8                       |
| character_set_database   | utf8                       |
| character_set_filesystem | binary                     |
| character_set_results    | utf8                       |
| character_set_server     | utf8                       |
| character_set_system     | utf8                       |
| character_sets_dir       | /usr/share/mysql/charsets/ |
+--------------------------+----------------------------+
8 rows in set (0.00 sec)

mysql> quit
Bye
|--------------------

The above looks OK, so we can skip 1 and 2 and continue with 2a, but if not you can follow the following procedure.

We want to have utf8 in the above character_set_* variables above (and NOT latin1)!

In order to do this:

1 - Create a backup of the MySQL configuration file (my.cnf):
|--------------------
# cd /etc
myhost:/etc # cp my.cnf my.cnf.ORIG
|--------------------

2 - Use vim to add these 3 lines in the section [mysqld] of the my.cnf file:
|--------------------
default-character-set = utf8
character-set-server = utf8
skip-character-set-client-handshake
|--------------------
In openSUSE 11.3 and the provided mysql packet only the default-character-set can be set, the other 2 should not be added.

2a - If you are unfamilar with SQL you should remove the #-character in front of safe-updates in that same section.

3 - Restart MySQL:
|--------------------
myhost:/etc # service mysql restart
Restarting service MySQL
Shutting down service MySQL                                           done
Starting service MySQL                                                done
|--------------------

Now, let's type again the show variables like 'char%' mysql command to see if
the character_set_variables have changed from latin1 to utf8 (character_set_filesystem
will still read "binary" but I think that's OK:
|--------------------
myhost:/etc # mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 5.1.46-log SUSE MySQL RPM

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> show variables like 'char%';
+--------------------------+----------------------------+
| Variable_name            | Value                      |
+--------------------------+----------------------------+
| character_set_client     | utf8                       |
| character_set_connection | utf8                       |
| character_set_database   | utf8                       |
| character_set_filesystem | binary                     |
| character_set_results    | utf8                       |
| character_set_server     | utf8                       |
| character_set_system     | utf8                       |
| character_sets_dir       | /usr/share/mysql/charsets/ |
+--------------------------+----------------------------+
8 rows in set (0.01 sec)

mysql> quit
Bye
|--------------------

== Create the Koha database ==

=== Create the koha database and user with associated privileges ===
|--------------------
# mysqladmin -uroot create koha -p
|--------------------
(you may name the koha database something different from koha)

=== Grant privileges to a MySQL user to the koha database ===

Assuming that you want to have a MySQL user called "kohaadmin" to administer a database called "koha" with the password "kohapassword", you'd enter this:
|--------------------
myhost:~ # mysql -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.1.46-log SUSE MySQL RPM

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> grant all on koha.* to 'kohaadmin'@'localhost' identified by 'kohapassword';
Query OK, 0 rows affected (0.00 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.08 sec)

mysql> quit
Bye
|--------------------

== Test your SAX Parser and correct where necessary ==

  * Install the XML::SAX and XML::LibXML perl Modules:

|--------------------
# zypper install perl-XML-SAX perl-XML-LibXML
Loading repository data...
Reading installed packages...
'perl-XML-SAX' is already installed.
There is an update candidate for 'perl-XML-SAX', but it is from different vendor. Use 'zypper install perl-XML-SAX-0.96-13.1.x86_64' to install this candidate.
'perl-XML-LibXML' is already installed.
There is an update candidate for 'perl-XML-LibXML', but it is from different vendor. Use 'zypper install perl-XML-LibXML-1.70-6.1.x86_64' to install this candidate.
Resolving package dependencies...

Nothing to do.
|--------------------

In the above you see that these two packets have been installed during system installation.
You also installed a repository for the language perl.
The message about a different vendor is about this repository.
You have to use "zypper dup" to install the newer versions from this repository, but this outside this tutorial.

You must be sure you're using the XML::LibXML SAX parser, not Expat or PurePerl, both of which have outstanding bugs (in 2008) with pre-composed characters. You can test your SAX parser by running:
|--------------------
# cd /root/koha-3.00.00/

myhost:~/koha-3.00.00 # misc/sax_parser_print.pl
|--------------------

You will probably see this:
|--------------------
XML::SAX::PurePerl=HASH(0x8356a4c)
|--------------------

If you're using PurePerl (you probably are) or Expat, you'll need to edit your ParserDetails.ini file to use the LibXML Parser.
To find the ParserDetails.ini file, you may use locate.
To do this, first update the locate database by running the updatedb command:
|--------------------
# updatedb
|--------------------

Then find ParserDetails.ini using locate:
|--------------------
# locate ParserDetails.ini
/usr/lib/perl5/vendor_perl/5.12.1/XML/SAX/ParserDetails.ini
|--------------------

OK. So, let's first do a backup of this ini file:
|--------------------
# cd /usr/lib/perl5/vendor_perl/5.12.1/XML/SAX/

myhost:/usr/lib/perl5/vendor_perl/5.10.0/XML/SAX # cp ParserDetails.ini ParserDetails.ini.ORIG
|--------------------

Edit this ParserDetails.ini file (with vim or other editor)

See if the first line contains this:
|--------------------
[XML::SAX::PurePerl]
|--------------------
If it does, replace this first line by the following:
|--------------------
[XML::LibXML::SAX::Parser]
|--------------------

Run the /root/koha-3.00.00/misc/sax_parser_print.pl command again.
This time, you should get the following output:
|--------------------
XML::LibXML::SAX::Parser=HASH(0x8356e0c)
|--------------------

== Install the Zebra package ==

Zebra is already in the standard repository of openSUSE 11.3, so it seems better to install it.
In the next chapter a question will be asked whether it is installed, so you better install it; no harm done.
Because you may need the documentation, that will also be installed.
Note that the package name is idzebra.

|--------------------
# zypper install idzebra idzebra-doc
|--------------------
You will notice that a few dependencies need to be resolved, so a few other packages are also installed.

== Run Koha's perl installer ==
|--------------------
myhost:/usr/lib/perl5/vendor_perl/5.10.0/XML/SAX # cd /root/koha-3.00.00
|--------------------
After installation of a number of CPAN/perl packages we will run perl Makefile.PL to run the Koha installer.


=== Using zypper to install CPAN modules ===

The author of the openSUSE 11.0 version of this page did a trial run with the Makefile.PL module, which showed a lot of unstalled perl modules and other software packages.
He used the names of these packages and installed the missing ones.
I collected all the missing packets and put them in the list below to install these packages before running Makefile.PL.
Doing the way he did provides more inside in the process, however it is tedious and I want to avoid that.
You still can go [[Koha_3.0.0_on_openSUSE_11.0#Run_Koha's_perl_installer|there]] and learn from that experience.

The commands show below need to be given one by one, because zypper will always ask for confirmation. However you can als also put more than one module name after the "zypper install" command.
|--------------------
# zypper install perl-Algorithm-CheckDigits
# zypper install perl-Biblio-EndnoteStyle
# zypper install perl-CGI-Session-Serialize-yaml
# zypper install perl-CGI-Session
# zypper install perl-Class-Accessor
# zypper install perl-Class-Factory-Util
# zypper install perl-DBD-mysql
# zypper install perl-Data-ICal
# zypper install perl-Date-Calc
# zypper install perl-Date-ICal
# zypper install perl-Date-Manip
# zypper install perl-DublinCore-Record
# zypper install perl-Email-Date
# zypper install perl-GD
# zypper install perl-GD-Barcode
# zypper install perl-HTML-Scrubber
# zypper install perl-HTML-Template-Pro
# zypper install perl-Lingua-Stem
# zypper install perl-MARC-Charset
# zypper install perl-MARC-Crosswalk-DublinCore
# zypper install perl-MARC-File-XML
# zypper install perl-MARC-Record
# zypper install perl-MIME-Lite
# zypper install perl-Mail-Sendmail
# zypper install perl-Net-LDAP
# zypper install perl-Net-Z3950-ZOOM
# zypper install perl-PDF-API2
# zypper install perl-PDF-Reuse
# zypper install perl-PDF-Reuse-Barcode
# zypper install perl-32bit
# zypper install perl-SMS-Send
# zypper install perl-Schedule-At
# zypper install perl-Text-CSV
# zypper install perl-Text-Iconv
# zypper install perl-XML-Dumper
# zypper install perl-XML-LibXSLT
# zypper install perl-XML-RSS
# zypper install perl-Text-CSV_XS
# zypper install perl-PerlMagick
# zypper install perl-Carp-Assert
# zypper install gd gd-devel
# zypper install xorg-x11-libXpm-devel
# zypper install libjpeg-devel
# zypper install fontconfig-devel
# zypper install libpng-devel
# zypper install libyaz-devel
|--------------------

== Running the Makefile.PL module to configure Koha ==

My installation is a UNIMARC installation, so I'm answering unimarc to the "MARC format for Zebra indexing (marc21, unimarc) [marc21]" question below.
If your Library uses the MARC21 format instead of UNIMARC, you should press ENTER to accept the default (which is marc21).

Because my bibliographic catalog will have mainly records in English and Arabic, I'm answering "en" (English) to the "Primary language for Zebra indexing (en, fr) [en]" question below.

Although I'm NOT using Zebra, I'm answering "yes" (the default choice) to the "Install the Zebra configuration files? (no, yes) [yes]" so I can set up Zebra later, if I decide to.

Also note that Zebra has been installed in this case.

Below is the result of running the "perl Makefile.PL" command (including my answers to the several questions):
|--------------------
myhost:~/koha-3.00.00 # perl Makefile.PL

By default, Koha can be installed in one of three ways:

standard: Install files in conformance with the Filesystem
          Hierarchy Standard (FHS).  This is the default mode
          and should be used when installing a production
          Koha system.  On Unix systems, root access is
          needed to complete a standard installation.

single:   Install files under a single directory.  This option
          is useful for installing Koha without root access, e.g.,
          on a web host that allows CGI scripts and MySQL databases
          but requires the user to keep all files under the user's
          HOME directory.

dev:      Create a set of symbolic links and configuration files to
          allow Koha to run directly from the source distribution.
          This mode is useful for developers who want to run
          Koha from a git clone.

Installation mode (dev, single, standard) [standard]

Please specify the directory under which most Koha files
will be installed.

Note that if you are planning in installing more than
one instance of Koha, you may want to modify the last
component of the directory path, which will be used
as the package name in the FHS layout.

Base installation directory [/usr/share/koha]

Since you are using the 'standard' install
mode, you should run 'make install' as root.
However, it is recommended that a non-root
user (on Unix and Linux platforms) have
ownership of Koha's files, including the
Zebra indexes if applicable.

Please specify a user account.  This
user account does not need to exist
right now, but it needs to exist
before you run 'make install'.  Please
note that for security reasons, this
user should not be the same as the user
account Apache runs under.

User account [koha]

Please specify the group that should own
Koha's files.  As above, this group need
not exist right now, but should be created
before you run 'make install'.

Group [koha]

Please specify which database engine you will use
to store data in Koha.  The choices are MySQL and
PostgreSQL; please note that at the moment
PostgreSQL support is highly experimental.

DBMS to use (Pg, mysql) [mysql]

Please specify the name or address of your
database server.  Note that the database
does not have to exist at this point, it
can be created after running 'make install'
and before you try using Koha for the first time.

Database server [localhost]

Please specify the port used to connect to the
DMBS [3306]

Please specify the name of the database to be
used by Koha [koha]

Please specify the user that owns the database to be
used by Koha [kohaadmin]

Please specify the password of the user that owns the
database to be used by Koha [katikoan] kohapassword

Koha can use the Zebra search engine for high-performance
searching of bibliographic and authority records.  If you
have installed the Zebra software and would like to use it,
please answer 'yes' to the following question.  Otherwise,
Koha will default to using its internal search engine.

Please note that if you choose *NOT* to install Zebra,
koha-conf.xml will still contain some references to Zebra
settings.  Those references will be ignored by Koha.

Install the Zebra configuration files? (no, yes) [yes]

Unable to find the Zebra programs 'zebrasrv' and 'zebraidx'
in your PATH or in some of the usual places.  If you haven't
installed Zebra yet, please do so and run Makefile.PL again.

Since you've chosen to use Zebra with Koha,
you must specify the primary MARC format of the
records to be indexed by Zebra.

Koha provides Zebra configuration files for MARC 21
and UNIMARC.

MARC format for Zebra indexing (marc21, unimarc) [marc21] unimarc

Koha supplies Zebra configuration files tuned for
searching either English (en) or French (fr) MARC
records.

Primary language for Zebra indexing (en, fr) [en] fr

Koha can use one of  two different indexing modes
for the MARC authorities records:

grs1 - uses the Zebra GRS-1 filter, available
       for legacy support
dom  - uses the DOM XML filter; offers improved
       functionality.

Authorities indexing mode (dom, grs1) [grs1] dom

Please specify Zebra database user [kohauser]

Please specify the Zebra database password [zebrastripes] zebrapassword

Since you've chosen to use Zebra, you can enable the SRU/
Z39.50 Server if you so choose, but you must specify a
few configuration options for it.

Please note that if you choose *NOT* to configure SRU,
koha-conf.xml will still contain some references to SRU
settings.  Those references will be ignored by Koha.

Install the SRU configuration files? (no, yes) [yes] no

Since you've chosen to use Zebra, you can also choose to
install PazPar2, which is a metasearch tool.  With PazPar2,
Koha can perform on-the-fly merging of bibliographic
records during searching, allowing for FRBRization of
the results list.

Install the PazPar2 configuration files? [no] no

Would you like to run the database-dependent test suite? (no, yes) [no]

Koha will be installed with the following configuration parameters:

AUTH_INDEX_MODE          dom
DB_HOST                  localhost
DB_NAME                  koha
DB_PASS                  kohapassword
DB_PORT                  3306
DB_TYPE                  mysql
DB_USER                  kohaadmin
INSTALL_BASE             /usr/share/koha
INSTALL_MODE             standard
INSTALL_PAZPAR2          no
INSTALL_SRU              no
INSTALL_ZEBRA            yes
KOHA_GROUP               koha
KOHA_INSTALLED_VERSION   3.00.00.096
KOHA_USER                koha
RUN_DATABASE_TESTS       no
ZEBRA_LANGUAGE           fr
ZEBRA_MARC_FORMAT        unimarc
ZEBRA_PASS               zebrapassword
ZEBRA_USER               kohauser

and in the following directories:

DOC_DIR                  /usr/share/koha/doc
INTRANET_CGI_DIR         /usr/share/koha/intranet/cgi-bin
INTRANET_TMPL_DIR        /usr/share/koha/intranet/htdocs/intranet-tmpl
INTRANET_WWW_DIR         /usr/share/koha/intranet/htdocs
KOHA_CONF_DIR            /etc/koha
LOG_DIR                  /var/log/koha
MAN_DIR                  /usr/share/koha/man
MISC_DIR                 /usr/share/koha/misc
OPAC_CGI_DIR             /usr/share/koha/opac/cgi-bin
OPAC_TMPL_DIR            /usr/share/koha/opac/htdocs/opac-tmpl
OPAC_WWW_DIR             /usr/share/koha/opac/htdocs
PAZPAR2_CONF_DIR         /etc/koha/pazpar2
PERL_MODULE_DIR          /usr/share/koha/lib
SCRIPT_DIR               /usr/share/koha/bin
SCRIPT_NONDEV_DIR        /usr/share/koha/bin
ZEBRA_CONF_DIR           /etc/koha/zebradb
ZEBRA_DATA_DIR           /var/lib/koha/zebradb
ZEBRA_LOCK_DIR           /var/lock/koha/zebradb
ZEBRA_RUN_DIR            /var/run/koha/zebradb

To change any configuration setting, please run
perl Makefile.PL again.  To override one of the target
directories, you can do so on the command line like this:

perl Makefile.PL PERL_MODULE_DIR=/usr/share/perl/5.8

You can also set different default values for parameters
or override directory locations by using environment variables.

For example:

export DB_USER=my_koha
perl Makefile.PL

or

DB_USER=my_koha DOC_DIR=/usr/local/info perl Makefile.PL

If installing on a Win32 platform, be sure to use:
'dmake -x MAXLINELENGTH=300000'

Checking if your kit is complete...
Looks good
Writing Makefile for koha

myhost:~/koha-3.00.00 #
|--------------------

== Create the Koha User and Group ==

|--------------------
# useradd koha

# passwd koha
Changing password for koha.
New Password:
Reenter New Password:
Password changed.

# groupadd koha
|--------------------

== Run make test ==
|--------------------
myhost:~/Koha # make test
cp koha-tmpl/opac-tmpl/prog/famfamfam/silk/error_go.png blib/OPAC_TMPL_DIR/prog/famfamfam/silk/error_go.png
cp opac/opac-changelanguage.pl blib/OPAC_CGI_DIR/opac/opac-changelanguage.pl
cp koha-tmpl/intranet-tmpl/prog/img/itemtypeimg/liblime-kids/card.gif blib/INTRANET_TMPL_DIR/prog/img/itemtypeimg/liblime-kids/card.gif
cp koha-tmpl/opac-tmpl/prog/famfamfam/mini/note.gif blib/OPAC_TMPL_DIR/prog/famfamfam/mini/note.gif

[many more lines beginning with "cp" should appear...]

t/Amazon.t .................. ok
t/Barcodes_PrinterConfig.t .. ok
t/Bookfund.t ................ ok
t/Bookseller.t .............. ok
t/Boolean.t ................. ok
t/Branch.t .................. ok
t/Calendar.t ................ ok
t/Charset.t ................. ok
t/Debug.t ................... # BEFORE use:     $debug is not defined
# BEFORE use: $cgi_debug is not defined
t/Debug.t ................... 1/3 #  AFTER use:     $debug is 0
#  AFTER use: $cgi_debug is 0
# Done.
t/Debug.t ................... ok
t/dummy.t ................... ok
t/Input.t ................... ok
t/Koha.t .................... ok
t/Languages.t ............... ok
t/Maintainance.t ............ ok
t/Output.t .................. ok
t/Record.t .................. ok
t/Review.t .................. ok
t/Scrubber.t ................ 1/10 # Note: scrubber test output will have whitespace collapsed for readability
# done.
t/Scrubber.t ................ ok
t/Stats.t ................... ok
All tests successful.
Files=19, Tests=47,  3 wallclock secs ( 0.06 usr  0.08 sys +  2.12 cusr  0.25 csys =  2.51 CPU)
Result: PASS
|--------------------
So here it shows all is OK. I don't expect any problems to appear, otherwise you may need to read the document on installing Koha on openSUSE 11.0.

== Run "make install" ==

Now, we will run make install:

|--------------------
myhost:~/Koha # make install
|--------------------
[Several lines starting with "Manifying" and many lines starting with "Installing" will scroll by...]
|--------------------
Installing /usr/share/koha/man/man3/serials::serial-issues.3pm
Installing /usr/share/koha/man/man3/C4::Context.3pm
Installing /usr/share/koha/man/man3/cataloguing::value_builder::unimarc_field_123f.3pm
Installing /usr/share/koha/man/man3/cataloguing::addbiblio.3pm
Installing /usr/share/koha/man/man3/cataloguing::value_builder::unimarc_field_128c.3pm
Installing /usr/share/koha/man/man3/tools::viewlog.3pm
Installing /usr/share/koha/man/man3/admin::branches.3pm

Koha's files have now been installed.

In order to use Koha's command-line batch jobs,
you should set the following environment variables:

export KOHA_CONF=/etc/koha/koha-conf.xml
export PERL5LIB=/usr/share/koha/lib

For other post-installation tasks, please consult the README.

# cd /etc
myhost:/etc #
|--------------------

== Create /etc/bash.bashrc.local ==
Create a file called bash.bashrc.local in the /etc directory:
|--------------------
myhost:/etc # vim /etc/bash.bashrc.local
|--------------------
Add these 2 lines in the file:
|--------------------
export KOHA_CONF=/etc/koha/koha-conf.xml
export PERL5LIB=/usr/share/koha/lib
|--------------------

Exit the shell and log back in.
|--------------------
myhost:/etc # exit
|--------------------
After logging back in, type the following commands to check if
the KOHA_CONF and PERL5LIB environment variables have been correctly set:
|--------------------
myhost:~ # env | grep KOHA
KOHA_CONF=/etc/koha/koha-conf.xml

myhost:~ # env | grep PERL5LIB
PERL5LIB=/usr/share/koha/lib
|--------------------

== Koha's Web Installer ==

Access Koha's web installer at:

http://192.168.1.16:8080/

Your browser will probably say that:
|--------------------
" The server at 192.168.1.16 is taking too long to respond."
|--------------------
OK... It seems that we have still have to do something.

== Create a symbolic link to /etc/koha/koha-httpd.conf ==

Let's create a symbolic link to the /etc/koha/koha-httpd.conf file in the /etc/apache2/vhosts.d directory
:
|--------------------
myhost:~ # cd /etc/apache2/vhosts.d/

myhost:/etc/apache2/vhosts.d # ln -s /etc/koha/koha-httpd.conf koha-httpd.conf
|--------------------

  * Restart Apache
|--------------------
myhost:/etc/apache2/conf.d # service apache2 restart
Syntax error on line 28 of /etc/apache2/conf.d/koha-httpd.conf:
Invalid command 'RewriteEngine', perhaps misspelled or defined by a module
not included in the server configuration
|--------------------

== Enable the mod_rewrite Apache module ==

OK... It seems that we need to enable the mod_rewrite Apache module:
|--------------------
myhost:/etc/sysconfig # a2enmod rewrite
|--------------------
If the above command seems NOT to work, for some reason, do this - edit /etc/sysconfig/apache2 and add the word "rewrite" (without the quotes) at the end of the APACHE_MODULES line, right before the right quote
|--------------------
myhost:/etc/sysconfig # service apache2 restart
Syntax OK
Shutting down httpd2 (waiting for all children to terminate)         done
Starting httpd2 (prefork)                                            done
|--------------------

== Change koha-httpd.conf ==

If you browsed again to http://192.168.1.16:8080 you would still get no answer. This is because we still have to do some changes to the koha-httpd.conf file. Unless you did not follow this tutorial and port 8080 is not open. Look back in this page to find out how.

First, let's create a backup of this file:
|--------------------
myhost:/etc/apache2/vhosts.d # cp koha-httpd.conf koha-httpd.conf.ORIG

myhost:/etc/koha # vim koha-httpd.conf
|--------------------

At the beginning of the koha-httpd.conf file, under the commented NameVirtualHost line, add the following line:
|--------------------
Listen 8080
|--------------------
In that file, you should find two VirtualHost sections: one for the OPAC area of Koha and the other one for the Intranet.
If the two virtualHost directives - the lines that start with <nowiki><VirtualHost</nowiki> - in that file are set for the IP Address 127.0.0.2, replace them by the correct IP address of your server.

That file will have 2 ServerName directives (one for each of the 2 VirtualHosts).
In those directives, you should have the IP of your server -or- the FQDN of your server (example: ServerName koha-server.univ.org).

Now, restart again Apache:
|--------------------
myhost:/etc/koha # service apache2 restart
Syntax OK
Shutting down httpd2 (waiting for all children to terminate)         done
Starting httpd2 (prefork)                                            done
|--------------------

Try to access the web page:

http://192.168.1.16/

If you get again the "It Works!" web page, you'll probably have to Refresh/Reload the page in your browser (press the F5 key).

After reloading the page, you should get the following error:
|--------------------
Forbidden

You don't have permission to access / on this server.

Additionally, a 403 Forbidden error was encountered while trying to use an
ErrorDocument to handle the request.
Apache/2.2.4 (Linux/SUSE) Server at 192.168.1.16 Port 8080
|--------------------

OK. Let's add then the following directive at the end of the koha-httpd.conf file:
|--------------------
<Directory /usr/share/koha>
  Order allow,deny
  Allow from all
</Directory>
|--------------------

Restart Apache:
|--------------------
myhost:/etc/apache2/vhosts.d # service apache2 restart
Syntax OK
Shutting down httpd2 (waiting for all children to terminate)         done
Starting httpd2 (prefork)                                            done
|--------------------

OK. Load again the following page in your web browser:

http://192.168.1.16


After some seconds you should be redirected to:

http://192.168.0.2/cgi-bin/koha/maintenance.pl

and see a Koha page with the following text:
"System Maintenance... we'll be back soon! If you have any questions, please contact the Site Administrator"

This is actually GOOD NEWS!  :)  It's now time to set up Koha in the Intranet interface.

To do that, browse to:

http://192.168.0.2:8080

You should see a page with the title "Welcome to the Koha Web Installer", and with a "Username" and a "Password" textboxes.

If not you may have forgotten to open the 8080 port.


You may now login with your koha administrator username and password and reply to the several questions you will be asked.

== Add Zebra Indexer ==

Add an entry in Koha user crontab to process scheduled added/updated/deleted records
indexing by Zebra. <script_dir>cronjobs/crontab.example contains examples for these cron jobs (and many more).

NOTE: The cronjobs should be setup under the kohauser (the default is 'koha', but
this is the user you set up in section 'Create the Koha User and Group').

Edit the crontab for the koha user by running
    $ sudo -u <kohauser> crontab -e

For Zebra indexing, you are looking for the example that begins with

    # ZEBRA INDEX UPDATES with -z option, incremental index updates throughout the day
    # for both authorities and bibs

It may be easiest to copy/paste the example into your own crontab and modify as necessary.

You can also configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra