koha installation, by Thomas Krichel

Installing mySQL

root@host:~# aptitude install mysql-server␍
The following NEW packages will be installed:
package list
number packages upgraded, number newly installed, number to remove and number not upgraded.
Need to get number MB of archives. After unpacking number MB will be used.
Do you want to continue? [Y/n/?] ␍

┌─────────────────────────────────────────┤ Configuring mysql-server-version ├──────────────────────────────────────┐
│ While not mandatory, it is highly recommended that you set a password for the MySQL administrative "root" user.  │
│                                                                                                                  │
│ If this field is left blank, the password will not be changed.                                                   │
│                                                                                                                  │
│ New password for the MySQL "root" user:                                                                          │
│                                                                                                                  │
│ mysql_root_password______________________________________________________________________________________________  │ 
│                                                                                                                  │ 
│                                                      <Ok>                                                        │ 
│                                                                                                                  │ 
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ 

Installing koha

First, we have to make sure we have the right Debian sources. You can look at the current sources with
root@host:~# cat /etc/apt/sources.list␍
The lines that start with # are comments, as is usual in text-based instruction files.
Edit /etc/apt/sources.list to make sure that you use the testing version of the operating system. For each line in that file that starts with
deb URL version part
where URL is a URL and version is a word, make sure there that version is “testing”.
Then, if they are not there already, you add the special repositories for koha and it's indexer zebra
deb http://debian.koha-community.org/koha squeeze main
deb http://ftp.indexdata.dk/debian wheezy main
You may see a complaint
The following signatures couldn't be verified because the public key is not available: NO_PUBKEY key
where key is some key. Do
gpg --keyserver wwwkeys.eu.pgp.net --recv-keys key
apt-key add /root/.gnupg/pubring.gpg
Do this for every key you get a complaint for. If the key can’t be found don’t worry it’s a minor problem.
You could also use
deb http://debian.koha-community.org/koha squeeze-dev main
for the first line, that will give you the development version, the very latest, greatest, but maybe not so stable version.
The version is addressed here as “squeeze”, rather than “testing”. Until 2011‒02‒06, “squeeze” was the same version as “testing”. Since then, the “testing” version is “wheezy”. Yet more into the future the testing distribution will have another codename. You need to be aware of that.
Update the packages list.
root@host:~# aptitude update␍
If this shows an error don't worry about it. Let us upgrade the packages
root@host:~# aptitude upgrade␍
There are basically three components to what we want to install. koha, the ILS, yaz, the Z39.50 client, and zebra the Z39.50 server. Knowing these keywords, we can conduct some searches for what it available
root@host:~# aptitude search koha␍
root@host:~# aptitude search zebra␍
root@host:~# aptitude search yaz␍
Then get all three with one stroke we can do something like
root@host:~# aptitude install koha idzebra-2.0 yaz␍
WARNING: untrusted versions of the following packages will be installed!

Untrusted packages could compromise your system's security.
You should only proceed with the installation if you are certain that
this is what you want to do.

package name list

Do you want to ignore this warning and proceed anyway?
To continue, enter "Yes"; to abort, enter "No": Yes␍
You can ignore this warning, entering, yes here as suggested.
 ┌─────────────────────────────────────────────────────────┤ Configuring koha ├──────────────────────────────────────────────────────────┐
 │                                                                                                                                       │ 
 │ The koha package must have a database installed and configured before it can be used.  This can be optionally handled with            │ 
 │ dbconfig-common.                                                                                                                      │ 
 │                                                                                                                                       │ 
 │ If you are an advanced database administrator and know that you want to perform this configuration manually, or if your database has  │ 
 │ already been installed and configured, you should refuse this option.  Details on what needs to be done should most likely be         │ 
 │ provided in /usr/share/doc/koha.                                                                                                      │ 
 │                                                                                                                                       │ 
 │ Otherwise, you should probably choose this option.                                                                                    │ 
 │                                                                                                                                       │ 
 │ Configure database for koha with dbconfig-common?                                                                                     │ 
 │                                                                                                                                       │ 
 │                                        <Yes>                                           <No>                                           │ 
 │                                                                                                                                       │ 
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ 
┌──────────────────────────────────────────────────────┤ Configuring koha ├──────────────────────────────────────────────────────┐
│ Please provide the password for the administrative account with which this package should create its MySQL database and user.  │ 
│                                                                                                                                │ 
│ Password of the database's administrative user:                                                                                │ 
│                                                                                                                                │ 
│ mysql_root_password_______________________________________________________________________________________                      │ 
│                                                                                                                                │ 
│                                     <Ok>                                         <Cancel>                                      │ 
│                                                                                                                                │ 
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ 
┌──────────────────────────────────────────────────────┤ Configuring koha ├──────────────────────────────────────────────────────┐
│ Please provide a password for koha to register with the database server.  If left blank, a random password will be generated.  │ 
│                                                                                                                                │ 
│ MySQL application password for koha:                                                                                           │ 
│                                                                                                                                │ 
│ koha_mysql_password____________________________________________________________________________________________________________ │ 
│                                                                                                                                │ 
│                                     <Ok>                                         <Cancel>                                      │ 
│                                                                                                                                │ 
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ 
 ┌────┤ Configuring koha ├─────┐ 
 │                             │ 
 │                             │ 
 │ Password confirmation:      │ 
 │                             │ 
 │ koha_mysql_password_______   │ 
 │                             │ 
 │    <Ok>        <Cancel>     │ 
 │                             │ 
 └─────────────────────────────┘ 
Setting up koha-common (version) ...
Starting Koha ILS: daemonexecutablename.
Setting up koha (version) ...
dbconfig-common: writing config to /etc/dbconfig-common/koha.conf
Creating config file /etc/dbconfig-common/koha.conf with new version
Creating config file /etc/koha/koha-conf.xml with new version
granting access to database koha for koha@localhost: success.
verifying access for koha@localhost: success.
creating database koha: success.
verifying database koha exists: success.
dbconfig-common: flushing administrative password
Please see /usr/share/doc/koha/README.Debian for instructions on how to configure things after installing the koha package.
We are now ready to run the post installation script.
root@host:~# koha-post-install-setup␍
Module rewrite already enabled
Module suexec already enabled
Restarting web server: apache2.

Setting up koha installation

The Debian packages are build on the idea that a single koha installation may be able to support several libraries. Each library is characterized by a name. I will refer to these as the libname. You can, within reason, use any libname you like but I would recommend limiting it to contain the letters a to z, the numbers 0 to 9 and the underscore. If you can't for the life of you think of a libname, just use "library". Note that the libname may not contain certain characters, like uppercase characters.
Let's check again the documentation
root@host:~# less /usr/share/doc/koha/README.Debian␍
root@host:~# less /usr/share/doc/koha-common/README.Debian␍
We need to create a koha library. Don't read the man page, it does not seem to correspond to the actual usage. The following seems to work
root@host:~# koha-create --create-db libname␍
Koha instance is empty, no staff user created.
Enabling site libname.
Run '/etc/init.d/apache2 reload' to activate new configuration!
Restarting web server: apache2 ... waiting .
Starting Zebra server for libname
Against this advice, we will not restart Apache right now.
koha-create does a lot of things, one of them is to also have created a user libname_koha. It creates a database user koha_libname to access the database. It also creates creates a system user libname_koha, just to confuse us. It creates a random password for both users. Let's find out what that is
root@host:~# grep '<pass>' /etc/koha/sites/libname/koha-conf.xml␍
 <pass>randpa</pass>
So I am writing randpa for the randomly set password of your library. Let's test that the user can access mysql
root@host:~# mysql -u koha_libname -p␍
Enter password:randpa␍
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is number
Server version: version_number (Debian)

a lot of legalese

mysql> use  koha_libname;␍
Database changed
mysql> exit;␍
Bye
If there is a problem, we need to fix it manually. We need to login to mysql, setup the database and grant the user access to the database using the user name and password.
root@host:~# mysql -u root -p␍
Enter password:myslq_root_password␍
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is number
Server version: version_number (Debian)

a lot of legalese

mysql> create database koha_libname;␍
Query OK, 1 row affected (0.00 sec)
mysql> grant all on koha_libname.* to 'koha_libname'@'localhost' identified by 'randpa';␍
Query OK, 0 rows affected (0.00 sec)
mysql> exit;␍
Bye

Apache configuration for Koha

In this scenario, I assume you want to have your patron interface in the opac.domain and the staff interface in the koha.domain. If you are in class with Thomas Krichel, recall hostname is your hostname. You will have given that hostname to Thomas Krichel who will have created two domains for you, opac.hostname.openlib.org for the patron interface and koha.hostname.openlib.org for the staff interface. Also note we are using port 80 for both servers, I don't see a reason to do otherwise.
Apache can run many different virtual servers. Normally, each server has its own domain name. On Debian, Apache is configured to look for enabled server in /etc/apache2/sites-available/. We need to create a symbolic link to the koha server configuration. That configuration is stored in /etc/koha/koha-httpd.conf. That file is not writable by root, let us set it writable
We edit /etc/apache2/sites-available/libname.
ServerName libname
with
ServerName opac.domain
Treat the staff server in the same way. But there is additional change at the start. Replace
<VirtualHost *:8080>
with
<VirtualHost *:80>
because we us the default port 80 for both. Replace
ServerName libname:8080
with
ServerName koha.domain
Now you have to enable the site
host:~# a2ensite libname␍
You will see something like
Site libname already enabled
or you will see something like
Enabling site libname.
Run '/etc/init.d/apache2 restart' to activate new configuration!
In both cases is time to take this action!
host:~# /etc/init.d/apache2 restart␍
Actually a more elegant way to do the same thing is
host:~#  service apache2 restart␍
If you see some warning like
VirtualHost opac.domain:80 overlaps with VirtualHost koha.domain:80, the first has precedence, perhaps you need a NameVirtualHost directive
or some other warning like
 NameVirtualHost VirtualHost koha.domain:80 has no VirtualHosts
 NameVirtualHost VirtualHost opac.domain:80 has no VirtualHosts
then you understand why Thomas does not like Apache! This can only be solved with fiddling around with a bunch of files, Thomas will try to help.
The final check is to point your browser to http://ils_domain and http://koha_domain, where you will see the public and staff interfaces, respectively. We need the latter to go through the installation.

Running the Koha installer

We know point the web user agent at http://koha_domain. We know that our user name is koha_libname and that our password is randpar. Hopefully this will work.
Screen 0
The login screen.
Screen 1
Choose your language. The following assumes you have chosen “en” for English.
Screen 2
You should see “All dependencies installed.”
Screen 3
You are now told what the database settings are. They better be correct, if not you are out of luck since you can't change them here. If you click next, you should see: “Connection established.” “Database koha exists.” “User koha has all required privileges on database koha.” If you don't you must make sure your database settings correspond to those written out in the koha-conf.xml file.
Screen 4
It tells you it's ready. Click “next” to proceed.
Screen 5
It should say “Database tables created”, click “next”.
Screen 6
Follow the link to “install basic configuration settings”
Screen 7
Choose Marc21 rather than Unimarc. Make sure you choose something!
Screen 8
Since this is a test installation, check all items to import the samples. Note than some of the sample records may be cumbersome to delete later. But you could repeat the whole process if you want to do a real installation for production. In that case, you don't want to include the optional item. Click on “import”.
Screen 9
Here you get a list what was added, and one more option zebra or no zebra. Despite what it says the choose zebra. “Zebra: I have a large catalog, I understand I must configure Zebra after the installation has completed”.
Screen 10
Click finish.

Setting up Zebra

We first build the index
root@host:~# koha-rebuild-zebra libname
You may have to run this manually if you update your library holdings, to make them available in the search interface.
Then we start the indexing daemon
root@host:~# koha-start-zebra libname
You may have to run this command every time the machine boots.

Valid XHTML 1.0!