Debian Jessie development setup

This tutorial describes how to set up a complete development environment on a Debian Jessie machine using a gitified installation and a separate koha-specific Perl module directory.

Overview

A "gitified" installation is typically located in a user's home directory. The web server requires read access to this directory which is a potential security problem. Alternatively, the Koha source and installation directory can be moved to a location outside the user's home directory. This guide takes that approach.

Basic Setup

Create a directory in convenient location. We will use /var/koha:

~$ sudo mkdir /var/koha

Set owner and group to your user:

~$ sudo chown joefoo:joefoo

Allow yourself full access (read/write) while Apache 2 gets read access along with the world:

~$ sudo chmod 755

Once everything is done you will have 3 subdirectories in this location:

• Koha (cloned git repository)
• koha-dev (target installation directory for Koha)
• koha-perl (local Perl modules only used by Koha)

Git Clone

Change to the new directory and clone the official Koha repository:

~$ cd /var/koha
~$ git clone git://github.com/Koha-Community/Koha

As of May 2015 the total download size was about 1.2 GB in total, all of which will end up in the new subdirectory Koha.

Perl Modules

You will need a basic set of Perl modules to be able to run the installer:

~$ sudo apt-get install libdbix-connector-perl libnet-z3950-zoom-perl libxml-simple-perl libdatetime-timezone-perl

Additional Perl Modules

A number of Perl modules are not yet available in Debian Jessie. You will need to install them via CPAN. However, we do not want to have to install them system wide; they only need to be available to the Koha Perl installation. We will use the automatic tool CPANMinus to install the extra modules into a separate directory, which we then configure our Koha installation to search.

Install CPANM

The CPANMinus tool itself exists in the standard Debian repositories. Install it:

~$ sudo apt-get install cpanminus

Install Modules

$ cd /var/koha/
$ mkdir koha-perl
$ cpanm --local-lib /var/koha/koha-perl PDF::FromHTML

This will install the missing package PDF::FromHTML into /var/koha/koha-perl which will be our local library location for the Koha installation.

By using the standard Perl environmental variable PERL5LIB we can get Perl to look for modules in this new location. We will do this from the Apache 2 site configuration files which will make sure only Koha is affected.

MySQL Configuration

You need to create a database for koha, add a koha database user and grant that new user permissions to use the database. The default username is kohaadmin with the password katikoan. These are suggested during the Makefile setup, no need to write them down.

Open the MySQL command line prompt; you will need to know the password:

$ mysql -u root -p

Create a new database named koha:

mysql> CREATE DATABASE koha;
Query OK, 1 row affected (0.09 sec)

Create a new user named kohaadmin:

mysql> CREATE USER kohaadmin;
Query OK, 0 rows affected (0.20 sec)

Grant the user the necessary privileges on the new database:

mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, LOCK TABLES ON `koha`.* TO `kohaadmin`@`localhost`;
Query OK, 0 rows affected (0.35 sec)

Make sure the new privileges are applied:

mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.22 sec)

Now your database is ready for the installation of Koha.

Install Koha

This step configures the source code directory and writes content to the installation directory.

Generating the Makefile

You install Koha by running the interactive installer in a terminal/shell. Before you launch it, you should set up the environment variable PERL5LIB to point to your custom Koha Perl module location:

Koha$ export PERL5LIB=/var/koha/koha-perl/lib/perl5

This allows the installer to find all the custom modules that you have installed. If any of them are missing you will be prompted at the end of the install. Now launch the installer:

Koha$ perl Makefile.PL 

If the installer aborts with a message about missing modules you should just install them; preferrably through APT, secondly though CPANMinus. Every time you install modules through CPANMinus you should specify the local library location.

If the installer launches successfully you first choice will be installation type; choose dev. Then enter the location to your installation directory; /var/koha/koha-dev/ in our case. The rest of the options you should just accept the defaults on, with the possible exception of the username and password's configuration. For increased security these should not be left at the default values.

Once the configuration is complete you are ready to launch the installation. You might be prompted that you are missing some Perl modules or that some might be out of date:

Warning: prerequisite HTTPD::Bench::ApacheBench 0.73 not found.
Warning: prerequisite Test::DBIx::Class 0.42 not found.

To remedy the above warnings you simply need to use CPANMinus to install the correct versions into your custom Koha Perl module library:

$ cpanm --local-lib /var/koha/koha-perl HTTPD::Bench::ApacheBench Test::DBIx::Class

Building Koha

A standard Makefile has been generated which instructions for building and installing Koha. First we need to build the software:

Koha$ make

Once this step has completed successfully you can continue to the installation phase.

Installing Koha

The Makefile contains an installation target, named install by convention. Launch it:

Koha$ make install

You do not need to be a super-user for this since we have decided to install all the files into a location to which your regular user has write access. At the end of the installation you will be instructed to set up two environmental variables:

export KOHA_CONF=/var/koha/koha-dev/etc/koha-conf.xml
export PERL5LIB=/var/koha/Koha

The PERL5LIB variable is the same one we mentioned in the Additional Perl Modules section earlier. As you can see, Koha will be instructed to look for modules in the source git directory /var/koha/Koha. The KOHA_CONF variable is important if you need to run Perl scripts that interact with your Koha installation from the command line. Like for example a script to upgrade the database from one version to another.

Configuring Apache

Next we need to configure Apache to run the two web sites that Koha consists of; the front end called OPAC and the back end called Intranet. The OPAC front-end is intended for users (or "patrons") and the back-end for administrators and librarians).

The installer has generated an Apache 2 configuration file for you, located in the Koha installation directory: /var/koha/koha-dev/etc/koha-httpd.conf

It will contain two VirtualHost entries; one for the OPAC site and one for the Intranet site. These will be bound to the 127.0.1.1 address at port 80 and 8080 by default; which means they will only available to your local machine.

Listening Ports

Apache 2 does not listen to 127.0.1.1 by default. You will need to edit the file /etc/apache2/ports.conf and add the following lines:

Listen 127.0.1.1:80
Listen 127.0.1.1:8080

Once restarted Apache 2 will accept incoming connections on these ports for the local machine.

Enabling the CGI Module

The standard Apache 2 module cgi needs to be enabled for Koha to work. Enable it:

~$ sudo a2enmod cgi

If the CGI module is not enabled, the Perl scripts will not be processed and will be presented as downloads to user.

Editing the koha-httpd.conf File

You will need to edit a number of things in the /var/koha/koha-dev/etc/koha-httpd.conf file:

Granting Access to the Installation Directory

Add the following configuration for the source Koha directory. You need to add it twice; once for the OPAC site, once for the Intranet site. Place it inside the VirtualHost element:

<Directory "/var/koha">
    Require all granted
</Directory>

If you get 403 errors this is probably what you are missing.

Add the Custom Perl Modules

PERL5LIB is an environmental variable used by Perl to find it's modules. The value of it can be set via the SetEnv directive. You should be able to find an existing directive for both the OPAC and Intranet sites, inside the VirtualHost element:

SetEnv PERL5LIB "/var/koha/Koha"

As you can see, Perl is configured to look for models inside the Koha source directory already. We want to add our custom Perl module location in addition to the existing entry. Multiple locations can be entered if separated by a colon. Change the line to look like this:

SetEnv PERL5LIB "/var/koha/Koha:/var/koha/koha-perl/lib/perl5"

If you get errors about missing Perl modules, PDF::FromHTML in particular, the reason is probably that this environmental variable is not set up correctly.

Installing the Koha Web Site

Apache 2 will look for site configuration files in a special directory, /etc/apache2/sites-available/. Our file is located in a separate directory, so we need to create a symlink to the installation directory so that Apache 2 can find it:

$ sudo ln -s /var/koha/koha-dev/etc/koha-httpd.conf /etc/apache2/sites-available/koha.conf

Note that Apache 2 ignores the files unless they carry the .conf suffix.

Enabling the Koha Web Site

Now you can enable the new Koha site:

$ sudo a2ensite koha

This command will place a second symbol link in /etc/apache2/sites-enabled/ pointing to the first link we created. You will need to restart Apache 2 in order for all changes to take effect.

Restarting Apache 2

Since Debian Jessie has switched to using systemd the commands for restarting services has changed somewhat:

$ sudo service apache2 restart

Configuring the Zebra Indexer

Search indexing is currently provided by the GPL licensed Zebra engine: [1]

Installing:

$ sudo apt-get install idzebra-2.0

Currently under construction.

Configure Zebrasrv as service in systemd :

Systemd is the new system and service manager added since Jessie [2].

Create a file /etc/systemd/system/koha-zebra.service

[Unit]
Description=Koha Zebrasrv Service

[Service]
Type=simple
Environment="PERL5LIB=/var/koha/Koha"
Environment="KOHA_CONF=/var/koha/koha-dev/etc/koha-conf.xml"
User=koha
ExecStart=/usr/bin/zebrasrv -T -v none,fatal -f ${KOHA_CONF}

[Install]
WantedBy=multi-user.target

And enable the service :

$ sudo systemctl daemon-reload
$ sudo systemctl enable koha-zebra
$ sudo systemctl start koha-zebra

See also :

Zebra Manual [3]

Common Errors

Where the most common errors are listed along with known remedies.

Maintenance

After you have performed a git pull or fetch/merge cycle Koha will automatically enter Upgrade Mode. This requires the administrator to log in and complete the update via the staff intranet. The OPAC will be showing the "down for maintenance" message while this happens. Log into the staff intranet and complete the upgrade.

HTTP Error 403

You probably forgot to grant access in the Apache 2 configuration. Look in the access and error logs of Apache 2 for more details. If necessary, increase the verbosity of the logging.

File Download Instead of Page View

Apache 2 does not know how to process the file. Make sure you have enabled the cgi module:

~$ sudo a2enmod cgi

Can't call method "do" on unblessed reference at /var/koha/Koha/C4/Context.pm line 788.

This error is caused by a missing or misconfigured database connection. Check the web server log files:

[Thu Jun  4 15:37:21 2015] Auth.pm: DBI connect('dbname=koha;host=localhost;port=3306','kohaadmin',...) failed: Unknown database 'koha' at /usr/share/perl5/DBIx/Connector.pm line 32.
[Thu Jun  4 15:37:21 2015] mainpage.pl: Can't call method "do" on unblessed reference at /var/koha/Koha/C4/Context.pm line 788

As you can see, there is no database named koha in this case. This is probably because you forgot to set up the database before you executed the Web Installer.