Test major Koha Wiki changes or bug fixes here without fear of breaking the production wiki.
For the current Koha Wiki, visit https://wiki.koha-community.org .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 (master), 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.
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/master
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:
./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