Koha on ubuntu - packages

= Introduction =
Note: Ubuntu 16.04 support will reach end of life with Koha versions 18.11.18, 19.05.12 and 19.11.06.
*Ubuntu 14.04 LTS or earlier has not been supported since 2016. 
*These are the package installation instructions for Ubuntu. They have been tested using Ubuntu 16.04 LTS.
*For Bionic (Ubuntu 18.04 LTS), see this thread http://koha.1045719.n5.nabble.com/Koha-on-Ubuntu-18-04-LTS-Bionic-Beaver-td5975633.html
nano is a generic text editor. Please feel free to substitute your favourite editor (vi, emacs, gedit, or etc.). 
To help assist with the development and improvement of Koha, consider installing a git version. Try to learn version control using git! 
Do not attempt to correct tarball or git problems by following these instructions. 
These instructions are intended for the impatient or those who are skilled. The word library is the instance name and can be substituted with whatever is desired. Each box can be cut and paste into the terminal window as needed. Some commands are split into separate boxes, because intermediate prompts occur.
= 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 16.05.x series and the former stable version is the 3.22.x series. 
The versioning method has changed to YY.MM.x format reflecting YY.05 or YY.11 as stable releases, and YY.06 or YY.12 as the development release. Previously, R.even were stable and R.odd were development releases. The 3.22.x series was the last one under the older versioning method. 
== Install Ubuntu ==
Download and install Ubuntu Server (which is based on Debian) 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 instructions later. 
== Add a Koha Community Repository ==
If there are problems with these repositories, please confirm these instructions on the mailing list or IRC channel. 
 echo deb http://debian.koha-community.org/koha stable 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 development release: echo deb http://debian.koha-community.org/koha unstable 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- https://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
If this command complains "gnupg, gnupg2 and gnupg1 do not seem to be installed, but one of them is required for this operation", then install them and try again:sudo apt install gnupg gnupg1 gnupg2
== Update Ubuntu ==
This process, particularly the upgrade step, may take a while. 
 sudo apt update
 sudo apt upgrade
 sudo apt clean
== Download and install the latest Koha release ==
sudo apt install koha-common 
If you encounter problems, see Appendix B.
= Pre-Web Install Setup =
== Initial Configuration ==
To configure your server for use, edit /etc/koha/koha-sites.conf with details about your site. You may need to create this file. The contents of this file affect any Koha instances created on this server, so verify settings before creating an instance. You can use as a reference the file on /etc/koha/koha-sites.conf.dpkg-new. 
As an example, suppose you want to create an instance named mykoha with the domain names and ports set like this: 
*OPAC: mykoha-opac.mydomain.org:80 (port 80 is the default for web sites) 
*Intranet: mykoha-admin.mydomain.org:8080 (a different port that can be filtered)
You would set DOMAIN=".mydomain.org", INTRAPORT="8080", INTRASUFFIX="-admin", OPACPORT="80", OPACSUFFIX="-opac". See Appendix_A for a discussion of Name-based vs. IP-based installation, and Base_Install_Finished for an example of the how these affect the URL. 
sudo nano /etc/koha/koha-sites.conf  # Apache virtual hosts creation variables
DOMAIN=".myDNSname.org"
INTRAPORT="80" # use 8080 for an IP-based install.
INTRAPREFIX=""
INTRASUFFIX="-intra"
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
 # SQL file to load into new instances
DEFAULTSQL=""
 # Zebra global configuration variables
ZEBRA_MARC_FORMAT="marc21" # or normarc or unimarc.
ZEBRA_LANGUAGE="en" # match with installation language (e.g. es for Spanish)
BIBLIOS_INDEXING_MODE="dom"
AUTHORITIES_INDEXING_MODE="dom"
 # Memcached global configuration variables
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
 
Please see your Network Administrator to clarify any uncertainties for the DOMAIN entry.
== Instance Creation ==
These instructions assume a local database installation. 
== MariaDB or MySQL ==
You can either install MariaDB
 sudo apt install mariadb-server
*OR install MySQL server
 sudo apt install mysql-server 
You should then take a look at the DBMS_configuration page if you are using a version of Koha released before 18.05.00, 17.11.05 or 17.05.11
== Apache modules ==
The koha-create command writes out Apache configuration files. It requires the Apache mod_rewrite and mod_cgi modules to be enabled: 
 sudo a2enmod rewrite
 sudo a2enmod cgi
 sudo service apache2 restart
* The library is the instance name, and can be changed to anything required. It will affect the resulting URL. See Base_Install_Finished for an explanation of the URL. 
 sudo koha-create --create-db library
== Ubuntu Database Security Tweak ==
There is a security risk in Ubuntu's default set up (for MariaDB and MySQL). Type the following command: 
sudo 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 rest are all the default 'Y' (yes).
== Configuring Apache ==
=== Setup Default Ports ===
These instructions assume port 80 was used for INTRAPORT and OPACPORT. Changing values requires understanding Apache configuration files, which is beyond the scope of this document. Type the following command: 
sudo nano /etc/apache2/ports.conf 
/etc/apache2/ports.conf should contain one line like (do not delete lines!): 
Listen 80 
*Add it if it is missing. Comments start with #, remove the # if they are commented out. 
*Add also Listen 8080 (or whatever other port was chosen in the Initial Configuration section) if IP-based installation for intranet access. 
*Further educational reading: Apache Binding to Addresses and Ports
=== Enable Modules and Site ===
Now enable the apache modules this config needs, enable koha's configuration, and restart apache. 
sudo a2enmod deflate
sudo a2ensite library
sudo service apache2 restart 
If you encounter problems enabling the site, checkout Appendix B. 
== Determining an IP Address ==
=== Assumptions ===
In a home or corporate LAN, it is quite likely that your network setup has been configured with DHCP. If you are being hosted externally however, your machine likely has been given a static IP address, or it may be behind a reverse proxy. Because of the many possible complex configurations of networking involved, these instructions will attempt to guide you in the former simpler case. If you are unable to get to the Web Installation step or access Koha from another machine, please consult your system administrator, network administrator, or IT Department. We are unable to assist everyone with their networking configurations. 
=== Tweak Hosts File ===
The default configuration for the packages installation is based on fully qualified domain name set up. Since your fully qualified domain name may not be active yet, edit the /etc/hosts file to include it: 
sudo nano /etc/hosts 
/etc/hosts should have these two lines added (do not replace!): 
127.0.0.1		library.myDNSname.org
127.0.0.1		library-intra.myDNSname.org 
If you know the IP address, edit any other machine's /etc/hosts file with that IP address instead of 127.0.0.1. 
= Building Languages =
You may wish to install a variety of languages. If so, build them now using the appropriate language code. Check if your language code is available with koha-translate --list --available For example, to install France French: sudo koha-translate --install fr-FR 
= Web Installation =
Now you can visit your admininstration website to continue with the Koha web installer. The username to log in with will be koha_library. and you can get the password from this command 
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml;echo 
Navigate to your staff client page. You can do this by installing lynx and going there on your koha machine: 
 sudo apt-get install lynx
Lynx navigational keys include: tab to go between fields, enter (when not on text fields) to toggle or click, space to change pages (when not on text fields), Q to quit (when not on text fields). Arrows also work. 
lynx http://library-intra.myDNSname.org:80
If this gives a strange DBI connection error message, attempt to restart memcache (sudo service memcache restart) and try again.
= Setup Your Library in Koha =
After the web install, you should be redirected to the staff client login screen. 
*Login with koha user name and password. 
*Click on the More dropdown men and then on Administration. 
*Select Libraries, branches 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://{INTRAPREFIX}{InstanceName}{INTRASUFFIX}{DOMAIN}:{INTRAPORT}
 
The OPAC, or client page, can be accessed at: 
http://{OPACPREFIX}{InstanceName}{OPACSUFFIX}{DOMAIN}:{OPACPORT}
 
Where the values of {DOMAIN}, {INTRAPORT}, {INTRAPREFIX}, {INTRASUFFIX}, {OPACPORT}, {OPACPREFIX}, and {OPACSUFFIX} were defined in the Initial Configuration step, and {InstanceName} was defined in the Instance Creation step, though the example given said library. 
You should now have a functional Koha Installation 
= Further Configuration =
== E-mail ==
By default, email is turned off. This is to let you get everything set up before you risk sending unwanted notices to people. To turn email on: 
 $ sudo koha-email-enable libraryname
== Translations ==
Translations can be installed: 
 $ sudo koha-translate --install language-code
To see all the language codes:
 $ sudo koha-translate --list --available
== Seaching and non-latin languages ==
To get searching with non-latin languages (such as Russian, Chinese and Arabic) working correctly in Koha you need to setup and configure ICU.
== Other commands ==
There is a list of Commands provided by the Debian packages. All commands begin with koha-, and have man pages installed, for example: 
 $ man koha-create
= 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. 
 sudo apt-get update
 sudo apt-get upgrade
This should generally upgrade your koha-common. However, if the dependencies for koha have increased, you may have to: 
$ sudo apt-get install koha-common 
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 command which may take a long time (several hours) to complete for large databases: koha-upgrade-to-3.4 
It is always safest to run a full reindex after an upgrade, where {instance} is the name of your instance: 
 koha-rebuild-zebra -v -f {instance}
*On your librarians clients consider clear browser cache after upgrading.
= Uninstall Instructions =
The package installation method is unique in that a removal command is already provided. Determine what instances you have: 
$ koha-list 
And then for each instance: 
$ sudo koha-remove {instance} 
If you encounter any problems, please request help on the mailing list or IRC channel. 
After uninstalling all the instances, uninstall the koha-common package: 
$ sudo apt-get remove koha-common 
= Appendix A: Named-based vs. IP-based installations =
These instructions are for a name-based installation. If you do not understand editing hosts files, do not have any IT support whatsoever, and are unable to get past a "Server not found" error, or the OPAC maintenance screen, then you likely wish to do an IP-based installation. 
The koha-site.conf file that was created is for a name-based installation. Apache can tell whether you want the staff client or the OPAC based on the name you use. However, if you do not have a DNS entry and editing hosts files for every single machine in the world sounds unpleasant, then you likely want an IP-based installation. 
/etc/koha/koha-sites.conf 
# Apache virtual hosts creation variables 
DOMAIN=".myDNSname.org"
INTRAPORT="8080"
INTRAPREFIX=""
INTRASUFFIX=""
# 80 may have "It Works!" problems.
# default site could be used by other applications
OPACPORT="8081"
OPACPREFIX=""
OPACSUFFIX=""
# SQL file to load into new instances
DEFAULTSQL=""
# Zebra global configuration variables
ZEBRA_MARC_FORMAT="marc21"
ZEBRA_LANGUAGE="en"
BIBLIOS_INDEXING_MODE="dom"
AUTHORITIES_INDEXING_MODE="dom"
# Memcached global configuration variables
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_" 
This means that the OPAC client with be at http://ipaddress:8081/ The staff client will be at http://ipaddress:8080/ 
And assuming you use library as your instance name, if you do get around to having a proper NAME using DNS: 
*http://library.myDNSname.org:8081 will be the OPAC 
*http://library.myDNSname.org:8080 will be the Staff client.
= Appendix B: Troubleshooting =
Because of the way Apache 2.4 changed from 2.2, issues arose. As a result, you may likely encounter solvable issues. These are the recommended solutions.
== perl: warning: Setting locale failed. ==
 dpkg reconfigure locales
This will give you the ability to regenerate all the locales, so there can not possibly be able problems next time. Or, if there is time and energy to attempt, figure out which ones to check minimally to not trigger the issue.
== Some difficulties were encountered installing apache2-mpm-itk. ==
Launchpad has a bug report with some suggested steps that resolved the problem under Ubuntu 14.04: 
 sudo a2dismod mpm_event
 sudo a2enmod mpm_prefork
 sudo service apache2 restart
If this was during an installation of koha-common: 
 sudo apt-get install -f
== Apache site-available issues ==
When attempting to enable an apache site, it supposedly doesn't exist. Depending on the version of apache installed, sites of one form (e.g. /etc/apache2/sites-available/{SITENAME}) need to be renamed to another form (e.g. /etc/apache2/sites-available/{SITENAME}.conf). This should solve potential issues when you try to enable the site later in the instructions. Both on Apache 2.2 and 2.4, on a normal case you could disable a library instance with the command a2dissite library.conf && service apache2 reload. 
== 403 errors for Gitified or git clone installs ==
In Ubuntu 14.04 you may discover that your gitified install returns 403 errors - this is because of the changes to Apache directory security. A possible fix includes adding the following stanza to apache2.conf (could be added in the virtualhost, or in one of the koha-shared*.conf files as well): 
 <Directory /home/my-user/koha-src/koha/>
 Options Indexes FollowSymLinks
 AllowOverride None
 Require all granted
 </Directory>
== AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to suppress this message ==
Solution for Ubuntu 16.04: 
 echo "ServerName localhost" | sudo tee /etc/apache2/conf-available/fqdn.conf
 sudo a2enconf fqdn
test with 
 apachectl configtest
== AH00548: NameVirtualHost has no effect and will be removed in the next release /etc/apache2/ports.conf ==
Solution: Comment out: #NameVirtualHost *:80 
== It Works! ==
Your Apache configuration needs fixing, read Apache Virtual Hosts and Apache Port documentation. 
Category:Installation Category:Debian_Packages