Install and Setup Koha to use Git on a Development Server

Prerequisites

Installed a minimal debian system, sudo, vim, xorg, xterm, wdm, fluxbox, idesk, and iceweasel. (idesk is used for desktop icons in the fluxbox window manager.)

Add Koha and Zebra Sources

Prevent annoying password prompts:

 sudo ls

Create the file /etc/apt/sources.list.d/koha.list:

 echo deb http://debian.koha-community.org/koha unstable main | sudo tee /etc/apt/sources.list.d/koha.list 

Create the file /etc/apt/sources.list.d/zebra.list:

 echo deb http://ftp.indexdata.dk/debian jessie main | sudo tee /etc/apt/sources.list.d/zebra.list

Add the Keys:

 wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add - 
 wget -O- http://ftp.indexdata.dk/debian/indexdata.asc | sudo apt-key add - 

Update the Sources:

 sudo apt-get update

Install Koha

Make sure you have fully updated your machine:

 sudo apt-get update 
 sudo apt-get upgrade 

Install koha-common:

 sudo apt-get install koha-common 

Setup Koha

Enable the Apache Rewrite Module:

 sudo a2enmod rewrite 

Create a koha instance and Create the koha database:

 sudo koha-create --create-db instancename 

Create a koha instance and use a remote server:

 sudo koha-create --request-db mylibrary 

(See Appendix A for more details.)

Make sure the koha site is enabled:

 sudo a2ensite koha 

Edit the Apache2 ports.conf file to listen on port 8080:

 sudo vi /etc/apache2/ports.conf 

Insert the following line after the NameVirtualHost line for port 80:

 NameVirtualHost *:8080 

Insert the following line after the Listen line for port 80:

 Listen 8080 

Restart Apache2:

 sudo /etc/init.d/apache2 restart 

Find the passwords for koha:

 sudo less /etc/koha/sites/instancename/koha-conf.xml 

(You need the user and password near the end of the file to login to the setup page.)

Start fluxbox:

 startx 

Open the Iceweasel web browser:

 Right-Click->Applications->Network->Web Browsing->Iceweasel 

Start Koha Setup:

 http://localhost:8080 

Follow the onscreen instructions.

Install and Setup Git

Git is typically used for Development, Testing Bugs, Fixing Bugs, and Signing-Off on bug patches. (Git is not what you want for a typical Live/Production Server.)

---

Install Git:

 sudo apt-get install git-core 

Set your name and mail address in git:

 git config --global user.name "Your NAME"
 git config --global user.email "your@mail.com" 

Set up a SMTP server using gmail:

 git config --global sendemail.smtpserver smtp.gmail.com
 git config --global sendemail.smtpserverport 587
 git config --global sendemail.smtpencryption tls
 git config --global sendemail.smtpuser your_email@gmail.com
 git config --global sendemail.smtppass your_password 

Automatically fix whitespace errors in patches:

 git config --global core.whitespace trailing-space, space-before-tab
 git config --global apply.whitespace.fix 

Set Syntax Highlighting/Color UI:

 git config --global color.ui auto 

For further Git Configuration help:

 http://git-scm.com/book/en/Customizing-Git-Git-Configuration 

Clone the public repository:

 git clone git://git.koha-community.org/Koha-community/Koha.git kohaclone

(See Appendix B for HTTP instructions, if you are unable to connect to port 9418 on git.koha-community.org.)

Create a branch to work on:

 cd kohaclone
 git checkout -b mywork origin/master

(You want to apply patches to the origin/master branch for testing.)

Update multiple files to point to the kohaclone

tl:dr This step can be done in one go using the koha-gitify script. The script is kept up to date and is likely to be more correct than the instructions in this section.

In the example below I assume you have put your Git Clone Folder of Koha in your Home Directory. Replace USER/GitCloneFolder with your username and the name of your git clone folder.

In /etc/koha/apache-shared.conf:

 replace SetEnv PERL5LIB "/usr/share/koha/lib" with SetEnv PERL5LIB "/home/USER/GitCloneFolder" 

In /etc/koha/apache-shared-opac.conf:

 replace DocumentRoot /usr/share/koha/opac/htdocs with DocumentRoot /home/USER/GitCloneFolder/koha-tmpl
 replace ScriptAlias /cgi-bin/koha/ "/usr/share/koha/opac/cgi-bin/opac/" with ScriptAlias /cgi-bin/koha/ "/home/USER/GitCloneFolder/opac/" 
 replace ScriptAlias /index.html "/usr/share/koha/opac/cgi-bin/opac/opac-main.pl" with ScriptAlias /index.html "/home/USER/GitCloneFolder/opac/opac-main.pl"
 replace ScriptAlias /search "/usr/share/koha/opac/cgi-bin/opac/opac-search.pl" with ScriptAlias /search "/home/USER/GitCloneFolder/opac/opac-search.pl"
 replace ScriptAlias /opac-search.pl "/usr/share/koha/opac/cgi-bin/opac/opac-search.pl" with ScriptAlias /opac-search.pl "/home/USER/GitCloneFolder/opac/opac-search.pl" 

In /etc/koha/apache-shared-intranet.conf:

 replace DocumentRoot /usr/share/koha/intranet/htdocs with DocumentRoot /home/USER/GitCloneFolder/koha-tmpl
 replace ScriptAlias /cgi-bin/koha/ "/usr/share/koha/intranet/cgi-bin/" with ScriptAlias /cgi-bin/koha/ "/home/USER/GitCloneFolder/"
 replace ScriptAlias /index.html "/usr/share/koha/intranet/cgi-bin/mainpage.pl" with ScriptAlias /index.html "/home/USER/GitCloneFolder/mainpage.pl"
 replace ScriptAlias /search "/usr/share/koha/intranet/cgi-bin/search.pl" with ScriptAlias /search "/home/USER/GitCloneFolder/catalogue/search.pl" 

In /etc/koha/sites/instancename/koha-conf.xml:

 replace <intranetdir>/usr/share/koha/intranet/cgi-bin</intranetdir> with <intranetdir>/home/USER/GitCloneFolder/</intranetdir>
 replace <opacdir>/usr/share/koha/opac/cgi-bin/opac</opacdir> with <opacdir>/home/USER/GitCloneFolder/opac/</opacdir>
 replace <opachtdocs>/usr/share/koha/opac/htdocs/opac-tmpl</opachtdocs> with <opachtdocs>/home/USER/GitCloneFolder/koha-tmpl/opac-tmpl/</opachtdocs>
 replace <intrahtdocs>/usr/share/koha/intranet/htdocs/intranet-tmpl</intrahtdocs> with <intrahtdocs>/home/USER/GitCloneFolder/koha-tmpl/intranet-tmpl/</intrahtdocs>
 replace <includes>/usr/share/koha/intranet/htdocs/intranet-tmpl/prog/en/includes/</includes> with <includes>/home/USER/GitCloneFolder/koha-tmpl/</includes> 

Search for Missing Dependencies:

 cd /home/USER/GitCloneFolder
 ./koha_perl_deps.pl -m 

Mine displayed 2 missing dependencies:

 Crypt::Eksblowfish::Bcrypt
 Data::Pagination

(Note that it shows which Modules are Required.) (Crypt::Eksblowfish::Bcrypt is a required module.)

Install Missing Dependencies:

 sudo install libcrypt-eksblowfish-perl 

Restart Apache:

 sudo /etc/init.d/apache2 restart 

(It's a good idea to restart Apache just to be sure everything is working well.)

Navigate to localhost:8080: It may require you to upgrade the database and run another web installer, but shouldn't go through the whole web install again. Login with the Username/Password for the superlibrarian account you have created. Otherwise login with the user/pass specified in the /etc/koha/sites/instancename/koha-conf.xml. Then Create a superlibrarian account, log off, and login with the new superlibrarian account.

Working with git

Create a bugzilla report for the bug you are fixing, if a bug has not already been reported:

 http://bugs.koha-community.org/ 

Now you do some work. Such as editing a template file that is messed up or editing a file to fix a bug. Commit the file once you have finished making changes to the file.

Commit the file:

 git commit file

(Use "git commit -a" for a bunch of files.) You'll be asked to enter a comment for your patch. Start the first line with the bugzilla number.

"Bug NNNN blabla bla full description of what my patch does continued contnued ... "

Add [ENH] just after the patch number, if your patch is an Enhancement. (Instead of a bug fix.)

Show how your commit fits with all the other commits in this branch/clone:

 git log 

Update Git

Save your changes, Update git, Restore your changes:

 git stash save
 git fetch
 git rebase origin/master
 git stash apply 

Update git and wipeout your changes:

 git fetch
 git rebase origin/master 

Share git patch with the rest of the world

Create a patch and send it to the QA Manager:

 git format-patch origin
 git send-email 0001-filename 

Deleting Branches in git

Delete a branch:

 git branch -D branchname 

Delete multiple branches at once:

 git branch | grep "^ bug_" | xargs git branch -D 

Testing a patch using git and Signing-Off

Download the patch:

 wget -O <name_of_patch_file> http://bugs.koha-community.org/bugzilla3/attachment.cgi?id=<attachment_number>

(Or just go to the bugzilla page and download it using a web browser.)

Apply the Patch:

 git checkout -b qa_bug_xxxx
 git am -3 -i -u <name_of_patch_file>

Test it: Test the functionality of the patch. Does it do what is says it does? Does it do something it shouldn't?

Finish testing by running the following automated tests:

 prove t/ 
 prove t/db_dependent 
 prove xt/ 
 prove xt/author

(For all of the tests is xt/author to complete, you need the following perl modules:)

(Test::Pod, Test::Pod::Spelling, and Text::CSV::Unicode.)

Signing-Off:

Create a new signed-off patch, if the patch you tested is ok:

 git format-patch -s -l origin/master 

Attach the Signed-Off patch to the bugzilla post, and mark the bug as Signed-Off.

 https://bugs.koha-community.org/

Appendix A

Create koha instance and use a remote server:

Most of the instructions assume a local MySQL database server. If you intend to use an external or separate database server, it is important that you don't run koha-create --create-db mylibrary.

Instead, use the following steps:

 koha-create --request-db mylibrary 

Example output: root@web:~# koha-create --request-db mylibrary

See mylibrary-db-request.txt for database creation request.

Please forward it to the right person, and then run /usr/sbin/koha-create --populate-db mylibrary

Thanks. Restarting web server: apache2 ... waiting .

Show database request:

 cat mylibrary-db-request.txt 

Create a MySQL database and user on mysql as follows:

 database name: koha_mylibrary
 database user: koha_mylibrary 
      password: somerandomstring

Create MySQL database and set privileges. Use the database name, user name, and password specified in mylibrary-db-request.txt:

 ssh root@db 
 mysql -u root -p 

Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 20353 Server version: 5.1.49-3 (Debian)

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 current input statement.

 mysql> create database koha_mylibrary; Query OK, 1 row affected (0.00 sec) 

 mysql> grant all privileges on koha_mylibrary.* to 'koha_mylibrary'@'web.my.domain' identified by 'somerandomstring'; Query OK, 0 rows affected (0.17 sec) 

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

 mysql> exit Bye root@db:~# 

Populate the database:

 koha-create --populate-db mylibrary 

Koha instance is empty, no staff user created.

Enabling site mylibrary.

Run '/etc/init.d/apache2 reload' to activate new configuration!

Restarting web server: apache2 ... waiting .

Starting Zebra server for mylibrary root@web:~#

Appendix B

Cloning over HTTP:

 git clone https://git.koha-community.org/Koha-community/Koha.git kohaclone