Koha on ubuntu - packages long

Introduction

These instructions have been tested with Ubuntu 12.04 LTS and Ubuntu 13.04 specifically. We strongly recommend an LTS release, though anything higher should work.

The current supported versions of Koha include newer libraries, which are not easily available under previous LTS releases. So please, do not attempt to install Koha on anything prior to Ubuntu 12.04 LTS. Your success may vary, and you will not be supported.

From time to time you will see the word "nano." This is a generic text editor that works inside a terminal session. Please feel free to substitute your favourite editor (vi, emacs, gedit, or etc.) If a desktop version of Ubuntu is installed, which is not recommended, and you are unfamiliar with linux editors, the GUI gedit may be the preferred user-friendly editor of choice.

For example: The two instructions listed below are the same:

Type the following command in the terminal window:

sudo nano myimportantfile.cfg

Type the following command in the terminal window:

sudo gedit myimportantfile.cfg

These instructions focus on the recommended koha-common packages installation. Packages effectively do most of the difficult work. The koha-common package will automatically install koha's dependencies if they are not already present on your system. The only exception is that a local MySQL server is installed separately, because there is the possibility of using an external MySQL server. Other Installation methods, such as 'git' for assisting with development and improvements or 'tarball' which is not recommended and only mentioned for historical purposes, will not be discussed in this document. You can read the Debian package instructions for additional information.

If you are able to assist with the development and improvement of Koha and this isn't for a production environment, consider installing a git version. Git is a version control system. Try to learn version control using git!

The packages install, the git install, and the tarball install all have different directory structures. Do not attempt to correct tarball or git problems by following these instructions afterwards.

Pre-Installation Setup

Notation

Lines beginning with # or $ mean the suffix is a command that should be executed on the shell. That is, the part after given prompt. Don't type or copy the # or $ part. For instance:

$ sudo su -
...
# echo "Hello world"

means to run the commands sudo su - and echo "Hello world".

Lines beginning with > mean the suffix is a command that should be run within a MySQL shell. For example,

> SHOW DATABASES;

will show the available databases on a MySQL server.

Koha is released monthly, so keeping documentation up to date is difficult. Rather than saying 3.8.1, 3.8.2, 3.8.3, 3.8.4, or any other specific number, 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)
• Desktop edition
  

To keep your Koha installation minimal and to free resources for running, the Server edition is recommended, though the Desktop edition will be easier for beginners.

As Apache and MySQL will be installed in the instructions later, there is no need to select any extra packages during the installation of Ubuntu.

Add A Koha Community Repository

If you installed the Desktop version, Ubuntu defaults to a desktop called Unity. Run your mouse over the icons on the left and find "Dash Home" and left click it. Type "Terminal" on the top line. You will see a Terminal icon appear. Double click that icon. You will now be able to enter the commands in these instructions. Alternatively, you may use CTRL + ALT + 'T' to get the Terminal Screen.

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.

Getting prompted for a password in the middle of a command line is confusing. To prevent this:

$ sudo ls

Create Repository File

There are three repositories for Debian packages of Koha. They include required dependencies that are missing from Ubuntu. They represent different versions Koha:

• stable release
• old-stable release
• development release

The squeeze repository is the recommended default repository to use. To be a bit more conservative, the old-stable release can be used instead.

To install the current stable release, which is recommended:

$ 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

Install Repository Key

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

Now that you have added the appropriate repository, check to make sure Ubuntu is up to date. You may be prompted for the password of the user account you are signed in as.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get clean

This process, particularly the upgrade step, may take a while.

Installation Method

At this point, we are doing a packages installation. It will simplify installation and upgrade steps later. If development and patching will be done, consider using a git installation. For historical purposes, there is a tarball installation method as well.

Download and install the latest Koha release

Do the following command:

$ sudo apt-get install koha-common

Use Upgraded MARC::File::XML

$ wget http://ftp.ubuntu.com/ubuntu/ubuntu/pool/universe/libm/libmarc-xml-perl/libmarc-xml-perl_1.0.1-1_all.deb
$ sudo dpkg -i libmarc-xml-perl_1.0.1-1_all.deb

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.

$ sudo nano /etc/koha/koha-sites.conf

Some example content would be:

DOMAIN=".myDNSname.org"  # Change this to be your domain. Any instance will be a subdomain of this string.
INTRAPORT="80"  # TCP listening port for the administration interface
INTRAPREFIX=""  # For administration interface URL: Prefix to be added to the instance name.
INTRASUFFIX="-intra"  # For administration interface URL: Suffix to be added to the instance name.
DEFAULTSQL=""  # a value is generally not needed.
OPACPORT="80"  # TCP listening port for the users' interface (if you skip this, the apache default of 80 will be used)
OPACPREFIX=""  # For users' interface URL: Prefix to be added to the instance name.
OPACSUFFIX=""  # For users' interface URL: Suffix to be added to the instance name.
ZEBRA_MARC_FORMAT="marc21"  # Specifies format of MARC records to be indexed by Zebra. Possible values are 'marc21', 'normarc' and 'unimarc'
ZEBRA_LANGUAGE="en"  # Primary language for Zebra indexing. Possible values are 'en', 'fr' and 'nb'

Please see your Network Administrator to clarify any uncertainties for the DOMAIN entry.

If you follow the example without changing anything, you will get a working Koha system set up as http://library.myDNSname.org for the OPAC client and http://library-intra.myDNSname.org for the Staff client.

Should you be unable to get a domain name, change the INTRAPORT to 8080. Then access will be possible via the http://IPaddress:8080/ for the staff client and http://IPaddress/ for the OPAC client. The above sample represents the recommended settings, because library-intra.myDNS.org:8080 is an example of poor network configuration.

Instance Creation

Now you need to create your first koha instance. This instance will need a database. It can be external or local.

If you will be using a local database:

This may already be installed depending on what options were selected when installing Ubuntu. Run this anyways:

$ 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 service apache2 restart

Replace "library" with the name of your library. If you want to have library.myDNSname.org, then instancename can probably be "library". Use the following command, which rarely needs changes, to create a local database to create an instance called library:

$ sudo koha-create --create-db library

If you will be using an external database refer to the documentation

Ubuntu MySQL Security Tweak

There is a security risk in Ubuntu's MySQL default set up. Type the following commands:

$ mysql -u root -p
> USE mysql;
> SELECT host,user FROM user;

Under Ubuntu, newer versions of MySQL include anonymous connections. This is a security risk. They are listed with no username. Continue entering MySQL commands.

> DELETE FROM user WHERE user='';
> SELECT host,user FROM user;

The anonymous connections should be removed now. Continue entering MySQL commands.

> FLUSH PRIVILEGES;
> QUIT

The anonymous connections are removed.

Configuring Apache

Setup Default Ports

Then type the following command:

$ sudo nano /etc/apache2/ports.conf

Make sure there is an uncommented line like this in the ports.conf file (do not add it twice!):

Listen 80 

If you use a different set of port numbers in the INTRAPORT and OPACPORT back in the Initial_Configuration step, you will need to have a "Listen {INTRAPORT}" and "Listen {OPACPORT}", ensuring to change {INTRAPORT} and {OPACPORT} to the port numbers you chose.

Remember you chose an OPAC prefix or suffix and an Intranet prefix or suffix in an earlier step. This is how port 80 knows which files to access, because it uses named virtual hosts.

Make sure the NameVirtualHost line is uncommented like the following (do not add it twice!):

NameVirtualHost *:80

If you use a different set of port numbers in the INTRAPORT and OPACPORT back in the Initial_Configuration step, you will need to have a "NamedVirtualHost *:{INTRAPORT}" and "NamedVirtualHost *:{OPACPORT}", ensuring to change {INTRAPORT} and {OPACPORT} to the port numbers you chose.

Disable or Edit 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

You may wish to change the port number of the default site, but again always talk with your system administrator, network administrator, or IT Department. This can be done with: sudo nano /etc/apache2/sites-enabled/000-default
And then change the port number it uses: <VirtualHost *:4080>
4080 is an arbitrary port number. These commands should be used after consulting with 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. Replace "library" with the name of your library that you used in the "Instance Creation" section when you ran koha-create..

$ sudo a2enmod deflate
$ sudo a2ensite library
$ sudo service apache2 restart

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, please consult your system administrator, network administrator, or IT Department. We are unable to assist everyone with their networking configurations.

Private IP Addresses

The following IP ranges will not be available via the Internet:

• 10.0.0.0 - 10.255.255.255
  
• 172.16.0.0 - 172.31.255.255
  
• 192.168.0.0 - 192.168.255.255
  

Also, IP addresses in the range of 169.254.0.0 -169.254.255.255 are reserved for Automatic Private IP Addressing.

If you have a computer on the same network (as in the general home or corporate LAN scenario), you can use a nice graphical browser and the IP Address we determine to run the web install steps, and use Koha afterwards. If you have a hosted site with a fully qualified domain name, you may be able to use that. Otherwise, your scenario requires assistance from your hosting provider or network administrator. Regardless, the instructions as given and written will work to set up Koha.

Determine Address

Determine if there is at least one network card in it. Type the following:

$ sudo ifconfig

This should give output like:

eth0      Link encap:Ethernet  HWaddr 08:00:27:14:22:6c
          inet addr:192.168.69.38  Bcast:192.168.69.255  Mask:255.255.255.0
          inet6 addr: fe80::a00:27ff:fe14:226c/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:24087 errors:0 dropped:0 overruns:0 frame:0
          TX packets:29550 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:2968198 (2.9 MB)  TX bytes:4828089 (4.8 MB)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:11 errors:0 dropped:0 overruns:0 frame:0
          TX packets:11 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:3794 (3.7 KB)  TX bytes:3794 (3.7 KB)

In this example, there is "eth0" and "lo". "lo" is not accessible from another machine. "eth0" has an "inet addr" (IP Address) of "192.168.69.38".

If this IP address was not listed in the private IP addresses section above, it may be possible to use it as well. So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine by typing "http://" plus the name you have set for the intranet client (staff client) into the address bar. This is an external address. Attempt external addresses before private ones.

This example has a private IP address: "192.168.69.38". So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine on the same network by typing "http://library-intra.myDNSname.org/" into the address bar. This is because you will have put the address (eg. 192.168.69.38) and the fully qualified domain name into the /etc/hosts file of that other machine.

If there is more than one network card (e.g. eth1, eth2, etc.), attempt the IP Addresses in order until you have success or all fail. A typical failure is some sort of "time out" page. Eventually, you may just have to do a local install using 127.0.0.1, because other machines could not reach it.

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

Add (do not replace!) at the bottom, and the address you determined and what should be the fully qualified domain name. For example, the two lines added (one for the OPAC client, and one for the Staff Client) could look like this:

127.0.0.1		library.myDNSname.org
127.0.0.1		library-intra.myDNSname.org

If you were able to determine an IP address in the previous step, edit the other machine's /etc/hosts file with that IP address instead of 127.0.0.1.

Fully Qualified Domain Name

If you are hosted and you happen to know the fully qualified domain name (e.g. library-intra.myDNSname.org), you can attempt "http://library-intra.myDNSname.org:80/". This should not fail, if you have put the correct information into the hosts file.

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 and the password will be near the end of /etc/koha/sites/library/koha-conf.xml, where library is the instance name used by the koha-create command in the Instance Creation section. Make sure to replace library with your instance name. You will need to be root to view this You could also use this command:

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

to print it out.

Do this by navigating to your staff client page. The INTRAPREFIX, instance name, and INTRASUFFIX you used followed by the DOMAIN, a colon, and the INTRAPORT you gave in the Initial Configuration section make up the url. For example: http://library-intra.myDNSname.org:80

You can do this by installing lynx and going there on your koha machine:

$ sudo apt-get install lynx
$ lynx http://library-intra.myDNSname.org:80

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.

Web Installer Step 1

Choose Language

Use en for English.

Click Next

It will check to make sure all dependencies are installed. You will have to install

all items listed here, before you can continue.

It should say: All dependencies installed.

Click Next.

Web Installer Step 2

This shows the "Database settings".

Click Next

It will check to make sure it can connect to mysql, that the kohadata database

exists, and the user koha has all of the required privileges on the database

koha_library.

It should say:

Connection established.

Database koha_library exists.

User koha_library has all required privileges on database koha_library.

Click Next.

Web Installer Step 3

We are now ready to create the database tables and fill them with some default data.

Click Next.

It should say:

Success

*Database tables created

Click Next.

We are ready to do some basic configuration. Please install basic configuration settings to continue the installation.

Click on the link install basic configuration settings.

Select your MARC flavour.

Select Marc21.

Click Next.

Select Default Settings.

(Select everything, if you are testing.)

You may find it helpful to select all of the optional MARC frameworks.

One option that would be better to leave unchecked and to setup yourself in Koha is (sample_libraries). It adds about 10 sample libraries to koha. It is easy to enter your Library’s information in Koha and you will need to do that anyway.

Click Import.

It shows a list of items added and will report any errors here as well.

Click Finish.

Congratulations , Setup Complete.

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 dist-upgrade

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