Koha on ubuntu - packages

From Koha Wiki

Jump to: navigation, search
Home > Koha Versions > 3.14
Home > Koha Versions > 3.16

Contents

Introduction

These are the package installation instructions for Ubuntu. They have been tested using Ubuntu 12.04 LTS.

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 3.16.x series and the former stable version is the 3.14.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 instructions later.

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 squeeze 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 squeeze-dev 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 and install the latest Koha release

sudo apt-get 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.

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

/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"
ZEBRA_LANGUAGE="en"
BIBLIOS_INDEXING_MODE="dom"
AUTHORITIES_INDEXING_MODE="dom"

# Memcached global configuration variables
USE_MEMCACHED="no"
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 MySQL database installation:

sudo apt-get install mysql-server

The koha-create command writes out Apache configuration files. It requires the Apache mod_rewrite module to be enabled:

sudo a2enmod rewrite
sudo a2enmod cgi
sudo service apache2 restart
sudo koha-create --create-db library

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.

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).

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 two lines like (do not delete lines!):

NameVirtualHost *:80
Listen 80
  • They do not have to be in the same order. Add them if they are 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.
  • Apache 2.4 which comes with Ubuntu 14.04 does not require a NameVirtualHost line.

Disable Default Site

If you are running Drupal or any other web service on the same machine, do not disable the default site! If you are unsure, do not disable the default site! When in doubt, always talk with your system administrator, network administrator, or IT Department.

The following is intentionally not boxed to prevent problems arising from improperly disabling the default site.

If and only if Koha is the only thing on this server, then feel free to run this to disable the default site: sudo a2dissite 000-default

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.

Web Installation

Now you can visit your admininstration website to continue with the Koha web installer. The user name to log in with will be koha_library.

sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml

outputs the password needed to log in.

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

Read and follow all 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 the staff client login screen.
Login with koha user name and password.
Click on the More dropdown menu.
Select 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

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, in special cases, you may have to:

$ sudo apt-get install koha-common

Because the dependencies for koha have increased.

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}

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=""
OPACPORT="80"
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
USE_MEMCACHED="no"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"

This means that the OPAC client with be at http://ipaddress:80/ The staff client will be at http://ipaddress:8080/

And if you do get around to having a proper NAME using DNS:
http://library.myDNSname.org:80 will be the OPAC
http://library.myDNSname.org:8080 will be the Staff client. (assuming you use library as your instance name)

Appendix B: Troubleshooting

  • It is strongly recommended to use Ubuntu 12.04 LTS server. This will avoid problems. The next LTS came out, Ubuntu 14.04 LTS, and here are some of the problems encountered.

Under Ubuntu 14.04, some difficulties were encountered installing apache2-mpm-itk. Launchpad has a bug report with some suggested steps that resolved the problem:

sudo a2dismod mpm_event
sudo a2enmod mpm_prefork
sudo service apache2 restart
  • Under Ubuntu 14.04, while creating your instance, you may discover that only /etc/apache2/sites-available/{SITENAME} file was created. If you rename it to /etc/apache2/sites-available/{SITENAME}.conf this will solve potential issues when you try to enable the site later in the instructions.
  • In Ubuntu 14.04 you may discover that your gitified install returns 403 errors - this is because of the changes to Apache directory security. I fixed mine by 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>
  • Problem: While restarting apache: 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 14.4:

echo "ServerName localhost" | sudo tee /etc/apache2/conf-available/fqdn.conf
sudo ln -s /etc/apache2/conf-available/fqdn.conf /etc/apache2/conf-enabled/fqdn.conf
  • Problem: AH00548: NameVirtualHost has no effect and will be removed in the next release /etc/apache2/ports.conf

Solution:: Comment out: #NameVirtualHost *:80

Personal tools