Koha on ubuntu - git

= Introduction =
This is a shortened version of the Ubuntu Git Installation of Koha instructions. They have been tested. Use Ubuntu 14.04 LTS. 
nano is a generic text editor. Please feel free to substitute your favourite editor (vi, emacs, gedit, or etc.). 
To install Koha for production, it is recommended that you use packages. To help assist with the development and improvement of Koha, continue with these instructions and read more about version control using git! 
Do not attempt to correct tarball or package problems by following these instructions. 
These instructions are intended for the impatient or those who are skilled. Each box can be cut and paste into the terminal window as needed. Some commands are split into separate boxes, because intermediate prompts occur. 
These instructions set up a development system (main), not the current or former stable versions. As such, the install may not be as smooth as you wish. This is to be expected in a continually changing development system. 
As this will load all branches, this could be more time consuming that using koha-gitify, which turns a package installation into a git version.
= Pre-Installation Setup =
== Notation ==
For the most part, the boxed text is what goes on the command line or an MySQL prompt. However, when the box contains what you should see in a file (fully or partially), the file name will be bolded above the box.
Koha is released monthly, so keeping documentation up to date is difficult. The convention is to replace the last number with an x. For example, the current version is part of the 3.14.x series and the former stable version is the 3.12.x series.
== Install Ubuntu ==
Download and install Ubuntu from the official site. 
*Server edition (command-line only)
Do not install extra packages during Ubuntu installation. Apache2 and MySQL will be installed in the Ubuntu_Packages_from_List section (koha-deps has the dependencies).
== Add A Koha Community Repository ==
These instructions still function even though the latest version of Debian is wheezy. If the version has changed again, please confirm these instructions on the mailing list or IRC channel. 
sudo ls
echo deb http://debian.koha-community.org/koha unstable main | sudo tee /etc/apt/sources.list.d/koha.list 
To use the older stable release:echo deb http://debian.koha-community.org/koha oldstable main | sudo tee /etc/apt/sources.list.d/koha.list or to use the current stable release:echo deb http://debian.koha-community.org/koha stable main | sudo tee /etc/apt/sources.list.d/koha.list 
Add the key in gpg.asc to your APT trusted keys to avoid warning messages on installation. 
wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
== Update Ubuntu ==
This process, particularly the upgrade step, may take a while.
sudo apt-get update
sudo apt-get upgrade
sudo apt-get clean
== Download the latest Koha release ==
Git is recommended for a development environment. Either a packages installation or a git installation can be used in a testing environment. 
Install the base git installation first: 
sudo apt-get install git git-email 
Download Koha (make sure to substitute 'your name' and 'your@mail.com' appropriately): 
git clone https://git.koha-community.org/Koha-community/Koha.git kohaclone
cd kohaclone
git config --global core.whitespace trailing-space,space-before-tab
git config --global apply.whitespace fix
git config --global color.ui auto
git config --global user.name "your name"
git config --global user.email "your@mail.com"
git checkout -b mywork origin/main
 
The git clone will download about 2.6GB (Jan 2016).
== Install Dependencies ==
=== Ubuntu Packages from List ===
The repository added has koha-deps and koha-perldeps packages which make it very easy. Type the following: 
sudo apt-get install koha-deps koha-perldeps make
If you encounter a problem, try consulting http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages#Appendix_B:_Troubleshooting
You will encounter issues related to running the web installation step. Refer to http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages#403_errors_for_Gitified_or_git_clone_installs
=== Ubuntu Packages for Perl Dependencies ===
Check everything was installed, by running the test script to identifty missing libraries:
./misc/devel/koha_perl_deps.pl -m -u
 
Install any required libraries that are missing. It is a good idea to install optional ones that are easily found as well.
== Create MySQL Database and Grant Privileges ==
=== Create MySQL Database ===
If you have difficulty accessing MySQL's root acount, perhaps this Ubuntu page on resetting the root password may help.
mysql -u root -p
CREATE DATABASE koha; 
The Koha database has now been created with the name koha. It should now be listed.
=== Create User and Grant Permissions ===
Continue entering MySQL commands. Substitute a password of your choice for the {koha user password}'s in the following commands: 
CREATE user 'kohaadmin'@'localhost' IDENTIFIED by '{koha user password}';
GRANT ALL ON koha.* TO 'kohaadmin'@'localhost' IDENTIFIED BY '{koha user password}';
FLUSH PRIVILEGES;
QUIT 
The koha administrative user has now been created with the name kohaadmin and the password of your choosing.
= Configure Koha =
== User/Group Environment Variables ==
Since there is no need to actually create a koha user account for a git installation. Just set some environment variables for the process to pick up and use later:
export __KOHA_USER__=$USER
export __KOHA_GROUP__=$USER
echo $USER
The output of the echo command should match your user id, and since the user id and group id are generally the same for a freshly created account, this will make sure the indexing happens as this account.
== Generate Make file ==
Select defaults except as noted. 
perl Makefile.PL
Answer dev to the first question.
Recall that the database created is koha whose name was set in the Create MySQL Database step. This is the default answer.
The username and password were set up in the Create User and Grant Permissions step. The username is the default answer, but only you know the password chosen.
Give some thought should be given to the MARC format desired and the method of character normalization (chr or icu), though the defaults will work as MARC21 just fine.
Use the same username and password for the Zebra questions.
Don't worry about warnings generated by optional components.
= Build and Test Koha =
Having configured Koha, build it using the following command: 
make
Once this has successfully run, test Koha using the following command: 
make test
If this fails, it is likely due to a failed dependency. Remember, this is a development system and dependencies are not always up to date. You can determine the dependency by scrolling back and looking for something like: Can't locate Cache/Memcached/Fast.pm in @INC
Re-run make test after installing the missing library. For example, after several runs you may have typed
sudo apt-get install libcache-memcached-fast-perl
sudo apt-get install libdbd-mock-perl
= Install Koha =
Once the make test has successfully run, install Koha using the following command (follow any on screen prompts): 
$ make install
No sudo is required as you have access to the directories listed above.
Once this has successfully run, Koha is almost installed. There are only a few more steps left. 
At the end of this command the output will look something like the following, where {your user name} is the user from which you are doing the installation: 
Koha's files have now been installed.
In order to use Koha's command-line batch jobs,
you should set the following environment variables:
export KOHA_CONF=/home/{your user name}/koha-dev/etc/koha-conf.xml
export PERL5LIB=/home/{your user name}/kohaclone
For other post-installation tasks, please consult the README.
 
Take note of the two export commands as you will need them for a later step.
= Pre-Web Install Setup =
== Ubuntu MySQL Security Tweak ==
There is a security risk in Ubuntu's MySQL default set up. Type the following commands: 
mysql_secure_installation
The 'n' answer is case sensitive. You likely already set the root password when you installed MySQL. So the first answer is 'n'. The reset are all the default 'Y' (yes).
== Configure System Wide Environment Variables ==
Running scripts and cron jobs requires environment variables set. Use the following commands: 
sudo nano /etc/environment 
/etc/environment
KOHA_CONF=/home/{your user name}/koha-dev/etc/koha-conf.xml
KOHA_PATH=/home/{your user name}/kohaclone
PERL5LIB=/home/{your user name}/kohaclone
 
Change {your user name} to your actual user name!
logout
You will then need to log back in again.
== Configure and Start Apache ==
=== Place Koha Site File ===
sudo ln -s ~/koha-dev/etc/koha-httpd.conf /etc/apache2/sites-available/koha.conf
NOTE: Exclude the .conf if you are using Apache 2.2 or earlier.
=== Tweak Koha Site File ===
The default file limits connections to those from 127.0.1.1 (or 127.0.0.1), which is rather difficult to test/use in a server environment. Edit the file 
sudo nano /etc/apache2/sites-available/koha.conf
/etc/apache2/sites-available/koha will have a line that should have the IP address changed to a *: 
<VirtualHost *:80>
/etc/apache2/sites-available/koha will have another line that should have the IP address changed to a *: 
<VirtualHost *:8080>
=== Setup Default Ports ===
sudo nano /etc/apache2/ports.conf
/etc/apache2/ports.conf must have two lines exactly like:
Listen 80 
Listen 8080
Do not add them if they are already there.
/etc/apache2/ports.conf does not require NameVirtualHost:
#NameVirtualHost *:80
#NameVirtualHost *:8080
Do not add them if they are missing or already there. Just prepend # accordingly.
=== Disable Default Site ===
These short instructions assume that the default site is not needed: 
sudo a2dissite 000-default 
If this is not the case, talk to your system administrator, network administrator, or IT Department.
=== Enable Modules and Site ===
Now enable the apache modules this config needs, enable koha's configuration, and restart apache.
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2ensite koha
sudo service apache2 restart
== Setup Zebra ==
=== Server to Start on Boot Up ===
sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
sudo update-rc.d koha-zebra-daemon defaults
sudo service koha-zebra-daemon start
=== Configure Zebra Indexing ===
crontab -e 
add the following to the user cronjob 
# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and gets set when this process runs.
*/5 * * * *	$KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
= Web Installation =
You still need to configure/install Koha via the Admin Page. Navigate to: http://127.0.1.1:8080 
If you do not know how to do this, try installing lynx: 
sudo apt-get install lynx
lynx http://127.0.1.1:8080 
Login with koha user name and password. See the Create User and Grant Permissions section above, and follow the steps.
Your page will be redirected to the login page after completing installation.
= Setup Your Library in Koha =
After the web install, you should be redirected to: http://127.0.1.1:8080 
Login with koha user name and password. 
Click on the More dropdown menu. 
Select Administration. 
Select "Libraries and groups" under the "Basic Parameters" heading. 
Click New Library and enter your information into the form. 
Click Submit. 
Your Library is now setup in Koha.
= Base Install Finished =
The staff client, or administrative page, can be accessed at: 
 http://127.0.1.1:8080
The OPAC, or client page, can be accessed at: 
 http://127.0.1.1 
You should now have a functional Koha Installation
= Upgrade Instructions =
If you are running in another language other than English, please switch to English before doing the upgrade, the templating system has changed and the templates will need to be regenerated. Once you have upgraded, please regenerate your templates in your chosen languages. 
In order to upgrade, find the path to the koha install-log file:
find ~/koha-dev -name 'koha-install-log'
 
When upgrading from a previous installation of Koha 3, you can use the following from your current build directory:
perl Makefile.PL --prev-install-log /path/to/koha-install-log
make
make test
make upgrade
Koha 3.4.x or later no longer stores items in biblio records. If you are upgrading from a version older than Koha 3.4.x, run the following two commands which can take a long time (several hours) to complete for large databases:
    ./misc/maintenance/remove_items_from_biblioitems.pl --run
A full reindex is always a good idea too:
./misc/migration_tools/rebuild_zebra.pl -b -a -r -v
= Uninstall Instructions =
== Remove Koha Apache Files ==
sudo a2dissite koha
sudo rm /etc/apache2/sites-available/koha
sudo /etc/init.d/apache2 restart
== Disable and Remove Zebra Daemons ==
sudo update-rc.d koha-zebra-daemon remove
sudo rm /etc/init.d/koha-zebra-daemon
sudo update-rc.d koha-zebraqueue-daemon remove
sudo rm /etc/init.d/koha-zebraqueue-daemon
== Remove MySQL Database ==
mysql -u koha -p > drop database kohadata;
== Remove Zebra Indexes ==
sudo zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
sudo zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
== Remove Install Directories and Configuration Files ==
DISCLAIMER: The Command rm -r is an extremely powerful deletion tool. It will irrevocably remove what you tell it to. Use With Caution. 
=== Crontab Entries ===
sudo rm -r /etc/cron.d/koha
=== Install Directories and Configuration Files ===
You may not want to delete kohaclone if you wish to reinstall later. 
rm -r ~/koha-dev
rm -r ~/kohaclone
Category:Documentation
Category:Installation
Category:Installation_alternatives
Category:3.10
Category:3.12