There are three ways to install Koha: packages, git and tarball. These instructions focus on the packages installation. The packages method of installation is the recommended method. Packages effectively do most of the difficult work.

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

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.20.x series and the former stable version is the 3.18.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 work as well.

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

With the installation of Ubuntu done, you will need to tweak your repositories to install perl libraries which may not exist in the default Ubuntu repositories. So before we start, let's do:

This prevents the command from looking like it hung when it is actually waiting for a password. Now, let's get the signing key:

$ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

To install the repository for the latest stable release, which is recommended, use the following command:

$ echo deb http://debian.koha-community.org/koha squeeze main | sudo tee /etc/apt/sources.list.d/koha.list

There are currently three active repositories: oldstable, squeeze, and squeeze-dev. As of 2012-09-09, they represent 3.6.x, 3.8.x, and master respectively. This will change when 3.10.x is released. They will represent 3.18.x, 3.20.x, and master respectively.

To install the repository for the 3.8 release, which is recommended, use the following command:

echo deb http://debian.koha-community.org/koha oldstable main | sudo tee /etc/apt/sources.list.d/koha.list

It is important to note that when 3.22.0 is released, there will be no repository available for 3.18.x as 3.20.x will be moved to oldstable. This type of change happens roughly every 6 months.

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 the latest Koha release

Do the following command:

$ sudo apt-get install koha-common 

Pre-Web Install Setup

Initial Configuration

To configure your server for use with DNS names: After install, edit /etc/koha/koha-sites.conf with details about your site. You may need to create this file. Some example content would be:

You would set DOMAIN=".mydomain.org", INTRAPORT="8080", INTRASUFFIX="-admin", OPACPORT="80"

Next, you will need to enable the Apache mod_rewrite module:

$ sudo a2enmod rewrite

Under Ubuntu 14.04, some difficulties were encountered installing apache2-mpm-itk., some suggested steps that resolved the problem: 

sudo a2dismod mpm_event sudo a2enmod mpm_prefork sudo service apache2 restart

If apache2 restart showing error, run following command

$ sudo nano /etc/apache2/httpd.conf 

Add following line

ServerName localhost 

$ 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

$ sudo service apache2 restart

$ sudo a2dismod mpm_event

Run koha common command again,

$ sudo apt-get install koha-common

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 are uncertain, do a local installation.

If you will have a local database install mysql-server:

$ sudo apt-get install mysql-server 

Replace "library" with the name of your library. If you want to have library.framisdooby.org, then instancename can probably be "library". Then use the following command 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_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). 

Second Optopn 

$ 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:

Listen 80  

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:

NameVirtualHost *:80 

Disable or Edit Default Site

If the default site is not needed:

$ sudo a2dissite 000-default 

Now, skip to the next section.

If there is more than just one Koha website on this machine, you may wish to:

$ sudo nano /etc/apache2/sites-enabled/000-default 

And change the port number it uses:

<VirtualHost *:4080> 

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 rewrite $ sudo a2enmod deflate $ sudo a2enmod cgi $ 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.framisdooby.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 at the bottom, and the address you determined and what should be the fully qualified domain name. For example:

127.0.0.1  library.framisdooby.org 127.0.0.1  library-intra.framisdooby.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.frammisdoobie.org), you can attempt "http://library-intra.frammisdoobie.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 username 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.framisdooby.org:80

If you do not know how to do this, try installing lynx:

$ sudo apt-get install lynx $ lynx http://library-intra.framisdooby.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. All of the entries listed on this page were given to it when you ran the file Makefile.PL.

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

It should say:

Connection established.

Database kohadata exists.

User koha has all required privileges on database kohadata.

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.

The 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 ot 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

Enable multi language searching

To enable and configure ICU:

1. Install the yaz-icu package:

sudo apt-get install yaz-icu

2. In the staff interface go to More > Administration > Global system preferences > Searching.

3. Change the UseICUStyleQuotes system preference to Using.

4. Change the QueryFuzzy system preference to Don't try.

5. Change the QueryStemming system preference to Don't try.

6. Edit /etc/koha/zebradb/etc/default.idx

Change or add the bolded lines:

 # Traditional word index

 # Used if completenss is 'incomplete field' (@attr 6=1) and

 # structure is word/phrase/word-list/free-form-text/document-text

 index w

 completeness 0

 position 1

 alwaysmatches 1

 firstinfield 1

 icuchain words-icu.xml

 # Phrase index

 # Used if completeness is 'complete {sub}field' (@attr 6=2, @attr 6=1)

 # and structure is word/phrase/word-list/free-form-text/document-text

 index p

 completeness 1

 firstinfield 1

 icuchain phrases-icu.xml 

If the Koha instance is on a shared server and you only want to use ICU for this particular instance, this functionality was added in Bug 12216

7. Depending on the language you are searching, you may need to modify words-icu.xml or phrases-icu.xml - these are in the same directory as /etc/koha/zebradb/etc/default.idx. The ICU Chains Library covers the modifications required for several languages - you are encouraged to add more.

8. Restart Zebra and rebuild the search index.

If you are using packages (the recommended way to install Koha), run:

   sudo koha-zebra --restart {yourinstancename}

  sudo koha-rebuild-zebra -f {yourinstancename}

If you are using a git or tarball installation (not recommended for normal use) run these two commands (you will need to change the file paths to where they are on your system):

   /etc/init.d/koha-zebra-daemon restart

  /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -r -v -w 

 You may have to run these commands first: 

   sudo bash

  export PERL5LIB=/usr/share/koha/lib

  export KOHA_CONF=/etc/koha/sites/iesh/koha-conf.xml

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 

Source : http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages

Steps to install Koha Library Software on Ubuntu 20.04

1. Add GPG Key 

The packages we download have not been tempered, to ensure that, first, we will add the GPG key signed for Koha.

wget -q -O- https://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

2. Add Koha repository on Ubuntu 20.04

echo 'deb http://debian.koha-community.org/koha stable main' | sudo tee /etc/apt/sources.list.d/koha.list

To rebuild the APT cache, run the system update command:

sudo apt update

3. Command to Install Koha on Ubuntu 20.04

Once you added the Koha repo, we just need to execute a single command to download and install. Also, it automatically installs the Apache web server, so if you already have it then it is good otherwise leave that on Koha.

sudo apt install koha-common

4.  Install MySQL Server and configure a database

By default, on Ubuntu 20.04, the MySQL 8.0 version is available to install, use the below command.

sudo apt install mysql-server sudo systemctl start mysql

Now, secure your MySQL installation using the command:

sudo mysql_secure_installation

When it will ask for enabling Password Validation component which is the first step in securing MySQL, either you can ignore it or simply select the degree of password complexity you want to set for passwords.

Apart from it simply press Y key or as per your requirements for all coming options.

6. Create a Koha Instance on Ubuntu 20.04

Now, let’s create an instance for Koha:

sudo koha-create --create-db library

You can replace the library with the name of your library or whatever you would like to have. The name which you choose here will configure for apache, MySQL. username and other related components of Koha.

7. Configure koha sites ports

By default, it will use the port 80, however, I want that to be free for other future services on my web server, thus first I will change the default port in Koha sites configuration file.

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

Here, we change the Intraport to 8001 that will be used by Koha staff client. While leaving the OPAC (catalogue) to 8000.

INTRAPORT=”8001″

OPACPORT=”8000″

To save the file press CTRL+O followed by the Enter key and then CTRL+X.

8. Add Koha ports to Apache

Now, tell the Apache on what ports the Koha service is accessible, as in above steps we have used the 8001 for Koha staff client and 8000 for OPAC. Thus, mention the same in the Apache ports configuration file.

sudo nano /etc/apache2/ports.conf

Replace the line Listen 80 to following given one.

Listen 8001 Listen 8000

Save and Close – Ctrl+O and Ctrl +X.

8. Create Apache configuration files.

sudo a2enmod rewrite 

sudo a2enmod cgi 

sudo a2dissite 000-default sudo a2enmod deflate

sudo a2ensite library        Note: Replace the library with the Koha instace you have created in step 6

Restart Apache

sudo service apache2 restart

9. Zebra rebuild command

koha-rebuild-zebra -v -f library

10. Set password for the DB created by Koha

sudo mysql -u root -p

use mysql;

ALTER USER 'koha_library'@'localhost' IDENTIFIED WITH mysql_native_password BY 'XXXXXXX';

Note: Change h2smedia with the password you want to use. Remember this password will also use as administrator password to login Koho.

flush privileges;  SET GLOBAL sql_mode='';  

quit;

11. Change the password of the koha library database

To see the login password, you can use the command:

sudo koha-passwd library 

To manually change the default password created by the Koha, you can use the command:

sudo nano /etc/koha/sites/library/koha-conf.xml

Scroll down to the last and inside configuration change password.

Note: Change the library with your library name.

12. Restart memcached

sudo service memcached restart

13. Login to Web installer of Koha

http://localhost:8001 (Staff client)

http://localhost:8000 (Online catalogue)

Web installer › Perl modules missing

Some Perl modules are missing. Important: Required modules must be installed before you may continue.

• • HTTPD::Bench::ApacheBench

  • Version: 0.73

  • Usage: Load testing

  • Locale::Language Required

  • Version: 2.07

  • Usage: Core

  • Readonly::XS

  • Version: 0.01

  • Usage: Make script happy

  • Selenium::Remote::Driver

  • Version: 1.27

  • Usage: Testing suite

  • Test::DBIx::Class

  • Version: 0.42

  • Usage: Testing modules utilising DBIx::Class

  • Text::CSV::Unicode

  • Version: 0.40

  • Usage: Testing suite

When downloading Perl modules with cpanminus you must have make installed.

https://askubuntu.com/questions/1149446/cannot-install-perl-modules-on-ubuntu-18-04

sudo apt install cpanminus

sudo apt install cpanminus

sudo cpanm install Locale::Language

sudo cpanm install Readonly::XS

sudo cpanm Selenium::Remote::Driver

sudo cpanm Text::CSV::Unicode

sudo cpanm install HTTPD::Bench::ApacheBench

sudo cpan App::cpanminus

sudo apt install make

Since /usr/local/share/perl/5.26.1 and /usr/local/bin are "System" directories, regular users don't have write access to them.

The easiest fix to to run cpanm as root, with

sudo cpanm AnyEvent