Installing Koha 2.2.7 on Slackware 11

Radosław Moszczyński
r.moszczynskiREPLACE-WITH-YOU-KNOW-WHATuw.edu.pl

November 29, 2006
ver. 1.0

1 Installing required software

The order presented below is significant, so try following it if you want to avoid trouble!

1.1 MySQL

Prior to installing Koha, I didn’t have any experience with MySQL, so this part might be a little bit murky. It did work for me, but you should definitely consult the MySQL documentation.

Koha doesn’t support MySQL 5, which is the version that is packaged with Slackware 11.0. Therefore, I used the mysql-4.1.21 package that can be downloaded from the Slackware 10.2 repositories (the patches directory). The installation and configuration procedure is as follows:

  1. su to root, and install the MySQL package:
    # installpkg mysql-4.1.21-i486-1_slack10.2.tgz

  2. The installation should be seamless, as with most Slackware packages. Now you need to configure the software. First of all, the ownership of some files is set improperly, which makes initial configuration impossible. In order to correct it, issue the following as root:
    # chown mysql /var/lib/mysql/mysql/*

  3. Now it’s time for the initial configuration of the database engine:
    # mysql_install_db

  4. If everything went fine, you should now be able to start the MySQL server:
    # /etc/rc.d/rc.mysql start

  5. The last thing to do is take care of security and set all the necessary passwords. This is described in detail in http://mysql.org/doc/refman/4.1/en/unix-post-installation.html

1.2 YAZ Toolkit

The YAZ toolkit is used for building applications that make use of the Z39.50 protocol. There is a Slackware package available at http://www.linuxpackages.net, but I decided to build it from source, since the package is not up to date. In order to build it, you need to do the following:

  1. Download the YAZ toolkit package:
    $ wget http://ftp.indexdata.dk/pub/yaz/yaz-2.1.40.tar.gz

  2. Uncompress it:
    $ tar zxvf yaz-2.1.40.tar.gz

  3. Change to the newly created directory and issue the following commands:
    $ ./configure  
    $ make  
    $ su -c "make install"

  4. The YAZ toolkit should be ready for use.

1.3 Apache

Allegedly, Koha does not like Apache 1.x which is the version shipped with Slackware. There is a package with Apache 2.2.3 available at http://www.linuxpackages.net, but its logs displayed some database related mistakes and Koha didn’t run properly (this might have been caused by my improper configuration, though). I uninstalled it, but kept all the suggested packages it depends on (cyrus-sasl, db44, openldap-client, openssl), which are available from the Slackware 11.0 repositories.

I decided to build my own Apache from source, and I came across some information that due to some license-related issues Apache source-tree does not contain a MySQL interface. It is necessary to download and add it to the sources manually. Here’s how it is all done:

  1. Download the latest version of Apache (I used 2.2.3) from http://httpd.apache.org.
  2. Uncompress the package:
    $ tar zxvf httpd-x.x.x.tar.gz

  3. Download the file that contains the MySQL interface. It can be found here: http://apache.webthing.com/svn/apache/apr/apr_dbd_mysql.c. Move it to the proper directory:
    $ mv apr_dbd_mysql.c httpd-x.x.x/srclib/apr-util/dbd

  4. Now, issue the following sequence of commands:
    $ ./buildconf  
    $ ./configure  
    $ make  
    $ su -c "make install"

  5. That was easy, wasn’t it? It’s best to prepare a starting script to be put in /etc/rc.d. The easiest way is to use the one that comes with the official Apache package for Slackware. All you need to do is change the paths to apachectl, because they are different. Once you do this, type in this command as root:
    # /etc/rc.d/rc.apache2 start

  6. Apache should now be running. Start your favorite Internet browser and type in localhost in the address bar. You should see a webpage saying “It works!”

1.4 Perl modules

Koha has been written in Perl and relies on a great deal of extra modules that do not come pre-bundled with the Slackware Perl package. However, installing them is (in most cases) very easy. Here’s what you need to do:

  1. su to root and change to the /root directory:
    # cd

  2. For each package name provided below, issue the following command:
    # perl -MCPAN -e ’install "name-of-the-package"’

    The first time you run it, it will ask you some questions — use your common sense in answering them. The default answers are mostly OK. Whenever Perl wants to follow dependencies and install some additional packages, let it do so. Here are the packages:

  3. There’s several more required packages, but before moving on to them, you should deal with two whose installation is not so smooth and requires manual tinkering.
  4. The first one of them is DBD::mysql, and it allows Perl programs to communicate with your MySQL database server. First, try installing it like this:
    # perl -MCPAN -e ’install "DBD::mysql"’

    At some point the installation will die, because it does not know the password to your database server. But the package itself has been downloaded, so you can compile it manually. Here’s what you have to do:

    # cd .cpan/build/DBD-mysql-xxxxx  
    # perl Makefile.PL --testpassword=your_mysql_password  
    # make  
    # make install

    It should now install without any problems.

  5. There’s one module that I didn’t manage to install via the CPAN command line. However, manual installation is extremely easy:
    # wget http://cpan.org/modules/by-module/MARC/MARC-1.07.tar.gz  
    # tar zxvf MARC-1.07.tar.gz  
    # cd MARC-1.07  
    # perl Makefile.PL  
    # make  
    # make install

  6. Now you can follow with installing all the remaining modules, using the command provided above:

2 Installing and configuring Koha

2.1 Installation

After having configured all the necessary software, you are ready to install Koha itself. Don’t worry — the most difficult part is already behind you.

  1. su to root and change to the /root directory:
    # cd

  2. Download the Koha package:
    # wget http://download.savannah.nongnu.org/releases/koha/koha-2.2.7.tar.gz

  3. Uncompress it:
    # tar zxvf koha-2.2.7.tar.gz

  4. Change to the newly created directory and issue the following command:
    # ./installer.pl

  5. Now all you need to do is follow the installer’s prompts. The default answers are OK, but note them down (especially the installation paths and TCP ports) if you’re not logging the whole process. The only question which you should answer differently from what the installer suggests is the username. Instead of kohaadmin, type in root. This is the only way I could get the installer to properly set up the Koha database. This probably might be done in some other way, but I don’t know enough about MySQL administration. If you have any suggestions, mail me.

2.2 Apache configuration

The last thing to do is configure Apache. This consists of two steps:

  1. First of all, start your favorite text editor and adjust the /etc/koha-httpd.conf file to suit your needs. You should consult the Apache documentation, but here’s the file I use, maybe it can get you started:
    NameVirtualHost your_IP:8000  
    NameVirtualHost your_IP:9000  
     
    # KOHA’s OPAC Configuration  
    <VirtualHost your_IP:8000>  
       ServerAdmin your_mail_address  
       DocumentRoot /usr/local/koha/opac/htdocs  
       ServerName name_of_your_server:8000  
       ScriptAlias /cgi-bin/koha/ /usr/local/koha/opac/cgi-bin/  
       Redirect permanent index.html http://name_of_your_server/cgi-bin/koha/opac-main.pl  
       ErrorLog /usr/local/koha/log/opac-error_log  
       TransferLog /usr/local/koha/log/opac-access_log  
       SetEnv PERL5LIB "/usr/local/koha/intranet/modules"  
       SetEnv KOHA_CONF "/etc/koha.conf"  
    </VirtualHost>  
     
    # KOHA’s INTRANET Configuration  
    <VirtualHost your_IP:9000>  
       ServerAdmin your_mail_address  
       DocumentRoot /usr/local/koha/intranet/htdocs  
       ServerName name_of_your_server:9000  
       ScriptAlias /cgi-bin/koha/ "/usr/local/koha/intranet/cgi-bin/"  
       Redirect permanent index.html http://name_of_your_server/cgi-bin/koha/mainpage.pl  
       ErrorLog /usr/local/koha/log/koha-error_log  
       TransferLog /usr/local/koha/log/koha-access_log  
       SetEnv PERL5LIB "/usr/local/koha/intranet/modules"  
       SetEnv KOHA_CONF "/etc/koha.conf"  
    </VirtualHost>

  2. Now you need to add the following lines to the Apache configuration file (if you followed all the directions above, it should be /usr/local/apache2/conf/httpd.conf):
    Listen 8000  
    Listen 9000  
    Include /etc/koha-httpd.conf

2.3 Running Koha

Finally you’re ready to run Koha. Restart apache with the following command:

# /etc/rc.d/rc.apache2 restart

Open your favorite browser and type in the name of your server followed by one of the port numbers, depending on whether you want to take a look at the OPAC or the librarians’ interface. You can log in to the latter using the user name and the password you have chosen during Koha installation. Remember that you can always look them up in /etc/koha.conf.