Starting in Catalyst Koha team

From Koha Wiki
Jump to navigation Jump to search

This will be a guide for new employees starting in Koha Team, and is currently a Work in Progress.


So you've joined the Koha Team? Awesome! This is the guide to get you started.


The Koha Team

You can keep contact with the Koha team using the #koha IRC chat, useful to get access to this early in case you run into problems setting up your environment. Useful IRC chats to have around are:

  • The Koha Community #koha at irc.oftc.net:6667


Koha Documentation

Parts of Koha

There are a lot of parts that make up the Koha System, a full list of which you can find on Bugzilla. The main parts you will probably be concerned about are the following:

  • The OPAC - This stands for "Online Public Access Catalogue" it's the online version of Koha which corresponds to http://localhost:8080/ on your local instance and http://demo.mykoha.co.nz/ on the Catalyst Demo Koha. The perl scripts that provide the functionality of these pages are located in your /home/vagrant/kohaclone/opac/* folder in your KohaDevBox Vagrant instance.
  • The Intranet or Staff Interface - This is the part of Koha only accessible to staff which includes administration tools. This corresponds to http://localhost:8081/ in your local instance and http://demo-intra.mykoha.co.nz/ on the Catalyst Demo Koha. The perl scripts that provide the functionality of these pages are located throughout your /home/vagrant/kohaclone/* folder in your KohaDevBox Vagrant instance.

Setting up your Development Environment

 sudo apt-get install VirtualBox
  • Install Git
  • Install Vagrant
  • Install Ansible
  • Clone and set up your KohaDevBox
  • Once your KohaDevBox has been installed and initialised, change directory to the kohadevbox directory and use the "vagrant up" command to set up your VM. This can take a while!
 vagrant up
vagrant ssh


Setting Up Vim for Coding Perl


Common installation errors

There are several errors which can happen when you run the vagrant up command:

a) (Optional) try vagrant up (it may throw an error requiring you to install Ansible again, if it does throw an error type in the following): 

git clone git://github.com/ansible/ansible.git –recursive


b) (Optional) If it throws an error saying there is an issue with VBoxManage and the error is in the VagrantFile simply run the following command in the kohadevbox directory: 

git checkout 40e52a0b4c055f90b1811fe2af8415e0e5a18772

This is rolling back the branch to a commit where we know that the kohadevbox will work.


c) (Optional)If it says there is a issue with VT-d visualisation not enabled in the BIOS, restart the machine and press enter to bring up the BIOS, go to security->Visualisation and set both settings to [Enabled], as the issue is your BIOS is not enabling visualisation.


d) (Optional) When loading the intranet and/or OPAC if it just continues to load, check the intranet-error.log with this command:

tail -f /var/log/koha/kohadev/intranet-error.log

If it shows an error like this: 

[Fri Sep 29 00:43:02.523371 2017] [proxy_http:error] [pid 17602] (70007)The timeout specified has expired: [client 10.0.2.2:37034] AH01102: error reading status line from remote server httpd-UDS:0 
[Fri Sep 29 00:43:02.523461 2017] [proxy:error] [pid 17602] [client 10.0.2.2:37034] AH00898: Error reading from remote server returned by /index.html

What it is doing is Apache thinks that Plack is running when it isn't so what you need to do is check the Apache config and make sure it is actually disabled and then restart apache and try loading the localhost:8081 again.


When running through the Web installer and it asks you that Perl modules are misssing and that you need to install them write in this command to get the correct Mojolicious version:

sudo cpanm -i Mojolicious::Plugin::OpenAPI@1.15

And write in the command for the other two Perl modules:

sudo cpanm <perl_module_name>


Tools and Processes in Koha Development

It is important to become familiar with the Koha Coding Guidelines and Koha Development Workflow

Updating Koha

Ensure you keep your Koha up to date by regularly running the following in your kohaclone in vagrant. Koha updates often, so it's a good idea to run these weekly to stay with the latest version. 

git fetch
git checkout origin/master


Resetting the Koha database

If you need to reset your Koha database for whatever reason, you can use the following set of commands in your Kohadevbox vagrant instance to do so.

Make sure your Koha codebase is up to date: 

git fetch
git checkout origin/master

Back up your current database in case anything goes wrong. The default value for <instancename> is kohadev. 

sudo koha-dump <instancename>

Get your debian-sys-maint user credentials for the next step 

sudo cat /etc/mysql/debian.cnf

Delete the Koha database (and enter the password from the above command when prompted): 

mysqladmin -u debian-sys-maint -p drop koha_kohadev

Create the Koha database (and enter the password from the above command when prompted): 

mysqladmin -u debian-sys-maint -p create koha_kohadev

Go to the staff login page in your browser and go thorough the web installer: 

http://localhost:8081/

If you would like to add sample catalogue data to your database, now is a good time to follow the guide on that, a bit further down the page :) 

Load sample data (optional)

Reindex your Koha database 

sudo koha-rebuild-zebra -f -v kohadev


Testing and Signing Off Koha Patches

A good way to familiarise yourself with the different parts of Koha and how they work is to test and sign off patches for bug fixes. A quick guide to using git bz to apply and sign off patches can be found on the git bz configuration page under using git bz, a more detailed walk-through is provided below.

  1. Go onto the Bugzilla home page in your browser and click the 'search' button next to 'browse'.
  2. This will take you to a Basic Search form, click the link for Advanced Search right beside it.
  3. Under the 'Status' drop down menu, choose 'Needs Signoff', and then go to the bottom of the page and click Search.
    The difficulty of each entry depends on your knowledge of how to reproduce the bug and what it takes to test, so for a start you will be limited by your knowledge of the system. A good place to start is to go back to the Advanced Search, and selecting the "Staff Client" option, then see if you can find one dealing with changes to messages or text.
  4. When you click on a bug it will take you to a page with lots of information about it
    Alias, product, version, hardware, you don't need to play around with, they're important for documentation mostly, but aren’t really relevant to our testing.
    Version is important, it tells you which version of Koha the bug is in, this should almost always be master.
    Status is where the bug is at, so a newly reported bug will be called NEW, if someone submits a patch to fix it the status becomes Needs Signoff. When someone tests it and it works this becomes Signed Off, if it doesn't work then it Fails QA or Patch doesn't apply, depending on the error message. If it gets signed off, a higher team looks at it and it Passes QA, before being Pushed to Stable where it will be integrated in the next version release.
  5. Scroll down to the bottom of the page and open the attachment. This should have all the instructions for testing the bug.
  6. Carry out the testing.
    To access your Koha as a client would, use http://localhost:8080/ for Public interface and http://localhost:8081/ for the Staff interface.
    If you need credentials to log in you can find them in the file located in /etc/koha/sites/<instance_name>/koha-conf.xml in the KohaDevBox VM.
  7. To apply a patch, use the following command:
    git bz apply <bug_number>
  8. If you are happy to sign off on the patch (it works as expected according to the test plan) then use the following command:
    git commit --amend -s
  9. Now an editor will come up with your information already filled out, you can safely save and exit the file.
    If it opened in Nano you can use CTRL + W followed by CTRL + X to save and escape. In VIM you can use :wq followed by enter.
  10. Use the following command:
    git bz attach -e <bug_number> HEAD
  11. Your editor will open again, this time you need to uncomment the "Signed Off" status by moving the cursor down and removing the "#" in front of the line that says "# Signed Off"
    If it opened in Nano you can use CTRL + W followed by CTRL + X to save and escape. In VIM you can use :w then enter followed by :q and enter again.
  12. Check that it worked by going back to your browser and refreshing the bug page!
  13. Finally always do a "git checkout origin/master" before testing a new patch!


Checking Koha Warns

"Warns" are helpful debugging messages Koha uses to tell you what's going wrong in the system. To access these messages, there are two very helpful commands you can run from the kohadevbox (if you aren't running the kohadevbox, replace it with the name of your instance): 

sudo koha-shell kohadev

This will likely generate two error messages:

  • bash: cannot set terminal process group (-1): Inappropriate ioctl for device
  • bash: no job control in this shell

You can safely ignore both these error messages. Next run either this command for intranet related errors: 

tail -f /var/log/koha/kohadev/intranet-error.log

Or alternatively this one for OPAC related errors: 

tail -f /var/log/koha/kohadev/opac-error.log

This shows the 10 latest lines of the error.log file. It updates live so you can see any warnings or errors as they are produced while using Koha in your browser.


Loading Sample Data into Koha

For many tests you may need sample data (books and such) to work with. Loading the database with books yourself can be time consuming and also requires some specialist knowledge. Lucky for us there are files with catalogue data pre-prepared and readily available.


Patching Koha

Check out the Koha Community Git Guide!


When creating fixes and enhancements for Koha you should:

  • Create the bug in Bugzilla first if it does not exist yet.
  • Create a new branch in git referencing the bug name before making any additions or changes.
  • Ensure you write good commit messages.


How to Write a Good Commit Message:


Creating and Submitting your Patch:

Enchancements and Patching Bugs

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Starting_in_Catalyst_Koha_team&oldid=19683"