How to Install Koha Library System on Ubuntu Server 20.04 LTS

Koha Library Management System is the world’s first and most popular open-source library software, used by thousands of libraries worldwide. From small community libraries to large academic institutions like New York University, Koha is a reliable and cost-effective solution that delivers enterprise-class features, modules, and performance.

Compared to commercial options like Symphony, Millenium, and Horizon, Koha offers significant cost savings. For instance, Innovative Interfaces’ Sierra library system costs over $1 million for 25 licenses with a limitation of 100,000 items in the catalog, and requires paying more than $170,000 per year for support services. In contrast, Koha can cost you somewhere between $0 to ~$2,500 per year to run, with no limitations on the number of users, items, branches, or patrons. It includes all the essential features needed to run a library, such as circulation, cataloging, acquisitions, SQL reports, and many more.

This article will guide you through the Koha installation process on Ubuntu 20.04. However, keep in mind that installing Koha can be complex and requires a good knowledge of Linux server platforms and applications like Apache, MySQL/MariaDB, and Plack. Regular upgrades, updates, and troubleshooting for both Koha and your Ubuntu Server operating system are also necessary.

To begin the installation process, follow the steps below:

Prerequisites:

  •  A server running a fresh installation of Ubuntu Server 20.04 LTS.
  • SSH access to your server.
  • Your preferred text editor. We suggest vim or nano.
  • It’s best to use a clean, bare-bones server, but it’s always best practice to backup your data (including taking a snapshot of the entire server) in case anything goes wrong and you need to recover.
  • Do not install Koha on a production server with other software running on it. We suggest trying out the instructions on a development server first (a virtual server using VirtualBox or something similar will suffice).

You can copy and paste the following commands, but make sure you understand what you’re doing first.

Installation Steps:

1. Add the Koha community repository to your sources.

2. Add the Koha GPG Key.

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

3. Update and upgrade your server.

sudo apt update
sudo apt upgrade
sudo apt clean

4. Install the latest Koha Release.

sudo apt install koha-common

5. Install Apache web server if you haven’t already.

sudo apt install apache2

6. Install MySQL or MariaDB server (either works fine).

sudo apt install mysql-server

if you want to use a MySQL server or

sudo apt install mariadb-server

for MariaDB.

7. Secure your SQL server (MySQL or MariaDB from above).
The default MySQL/MariaDB server comes with anonymous users, root access, and a test database that is accessible by anonymous users. They should be removed in a production environment. Run the following command to get started and follow the instructions – they are fairly straightforward, answer “n” (for no) for the first question and “Y” (the default, yes) for the rest.

sudo mysql_secure_installation

8. Enable the Apache mod_rewrite modules.

sudo a2enmod rewrite
sudo a2enmod cgi
sudo systemctl restart apache2.service

9. Create the Library Instance.

sudo koha-create --create-db demo

“demo” can be anything you want (make it short, simple, and sensible though). This will be the name of your Koha library instance.

10. Choose between a name-based or IP-based installation.
a. Configure your server for a name-based installation. This will enable you to connect to your Koha instance using a domain or subdomain (you will need to point the A record of your domain/subdomain to your server’s public IP address). If you don’t have a domain or want an IP-based installation, skip this step and go to the next one (10b). You config file will be the same name as your instance name (the one you used above).


sudo vim /etc/apache2/sites-available/demo.conf
  • Your configuration file will be similar to the one below. It has two sections defining the VirtualHost – one for the OPAC and the other for the Staff page.
  • Replace the ServerAdmin email in both VirtualHost sections with your own (in this example, we use [email protected]). This will be visible to your users when they encounter a problem and will enable them to contact you.
  • Replace ServerName in both sections with the domain or subdomain you wish to use for your OPAC and Staff pages. In this example, we use opac.example.com for the OPAC and staff.example.com for the Staff page.
  • You may also want to add a ServerAlias for both domain/subdomain in both sections.
<VirtualHost *:80>

<IfVersion >= 2.4>

Define instance “demo”

</IfVersion>

Include /etc/koha/apache-shared.conf

# Include /etc/koha/apache-shared-disable.conf

Include /etc/koha/apache-shared-opac-plack.conf

Include /etc/koha/apache-shared-opac.conf


ServerAdmin [email protected]

ServerName opac.example.com

ServerAlias www.opac.example.com

SetEnv KOHA_CONF "/etc/koha/sites/demo/koha-conf.xml"

AssignUserID demo-koha demo-koha


ErrorLog /var/log/koha/demo/opac-error.log

# TransferLog /var/log/koha/demo/opac-access.log


</VirtualHost>


# Intranet

<VirtualHost *:80>

<IfVersion >= 2.4>

Define instance “demo”

</IfVersion>

Include /etc/koha/apache-shared.conf

# Include /etc/koha/apache-shared-disable.conf

Include /etc/koha/apache-shared-intranet-plack.conf

Include /etc/koha/apache-shared-intranet.conf


ServerAdmin [email protected]

ServerName staff.example.com

ServerAlias www.staff.example.com

SetEnv KOHA_CONF "/etc/koha/sites/demo/koha-conf.xml"

AssignUserID demo-koha demo-koha


ErrorLog /var/log/koha/demo/intranet-error.log


# TransferLog /var/log/koha/demo/intranet-access.log


</VirtualHost>

b. Configure your server for an IP-based installation. If you don’t have a domain or simply want to use access your Koha instance using an IP address, do the following (skip this step if you are using a name-based installation):

  • Decide which ports use.

In this example,we’ll use 7001 for the OPAC and 7002 for the Staff page but it can be anything you like (except ports 0 – 1023, these are reserved ports and are used by default by various applications). If you are using a firewall (which you should!) allow access to these two ports.

  • Open your instance config.
sudo vim /etc/apache2/sites-available/demo.conf
  • Change the virtual host of your OPAC section from 
    <VirtualHost *:80>

    to

    <VirtualHost *:7001>

    .

  • Change the virtual host of your Staff section from 
    <VirtualHost *:80>

    to

    <VirtualHost *:7002>

    .

  • Replace the ServerAdmin email in both VirtualHost sections with your own (in this example, I use [email protected]). This will be visible to users when they encounter a problem and enable them to contact you.
  • Close and save your config file.
  • Edit your ports.conf and add your two ports to the Listen directive
sudo vim /etc/apache2/ports.conf
  • Add the following lines below the existing directives (you should have Listen 80 already enabled. Do not delete any directives that you find in this file, unless you know what you’re doing of course).
Listen 7001
Listen 7002
  • Close and save the file.

11. Enable your Koha instance.


sudo a2enmod deflate
sudo a2ensite library

12. Check your Apache config for syntax errors and restart.

sudo apachectl configtest

This command should return “Syntax Ok”. If not, go back to your config file (/etc/apache2/sites-available/demo.conf) and fix any errors. Then run:

sudo systemctl restart apache2

13. Point your OPAC and Staff domain/subdomain to your Koha server.

To access your OPAC and Staff via the URL, you need to update the DNS A-records of your domain or subdomains and point them to your server’s public IP address (you may already have done this when you created them. If so, ignore this step and move on). How you do this depends on your domain hosting provider, it’s usually a pretty easy and straightforward process.

14. Complete the web setup.

To complete Koha’s web setup, you will need your admin username and password. My instance is called demo, so my username is koha_demo (if your instance is called library, your username will be koha_library, etc.). To get the password, run this command in your terminal (replace demo with your library name):

sudo koha-passwd demo

Open a web browser and go to your staff URL (staff.example.com for me). The web installer will look something like this:

15. Enter your username and password and follow the prompts.

Complete Koha’s web setup by opening a web browser and entering your admin username and password. Follow the prompts to complete the installation. If you encounter any errors, try the troubleshooting steps provided in the guide.


sudo vim /etc/apache2/sites-available/demo.conf

Troubleshooting Koha Installation Errors

If you get Error 500 or other errors, try the following:

1. Make sure your Koha instance is enabled. Run:


 sudo koha-enable demo

2. Make sure your Koha instance worker is up and running:


sudo koha-worker --status demo

sudo koha-worker --start demo

If it’s already running, try restarting the worker process:


sudo koha-worker --restart demo

3. Make sure Zebra is running:


sudo koha-zebra --start demo

4. Make sure Plack is running. Run:


sudo koha-plack --enable demo

sudo koha-plack --start demo

5. Make sure you can access the MySQL or MariaDB

A quick way to check if your Koha instance can access the database is by running the following command:


sudo koha-mysql demo

You should be able to log in to the MySQL console. If you encounter an error similar to “ERROR 1698 (28000): Access denied for user ‘koha_demo’@’localhost’” then it may be due to the  MySQL plugin being used for the Koha user (learn more about MySQL plugins). You can find out which plugins are being used by running:


sudo mysql

to login to the console as root if your root user is using the auth_socket plugin, otherwise login using:


mysql -u root -p 

In the MySQL console, you can see the plugins being used for each user by running:


mysql> SELECT user, host, plugin FROM mysql.user;

If your Koha user (koha_demo, where demo is the name of the Koha instance) is using the ‘auth_socket’ plugin, you need to drop and recreate the user by doing the following: 

Retrieve the Koha instance user database password

Open another terminal and run the following command.


sudo koha-passwd demo

This command will output the Koha administrator user password. Copy the password, you’ll need it for the following steps.

Go back to the MySQL console and do the following:


mysql> DROP user 'koha_demo'@'localhost';

mysql> CREATE user 'koha_demo'@'localhost' IDENTIFIED BY 'THE-PASSWORD-YOU-COPIED-ABOVE';


mysql> GRANT ALL PRIVILEGES ON koha_demo.* TO 'koha_demo'@'localhost';


mysql> FLUSH PRIVILEGES; 


mysql> EXIT;

Now you can try again to log in to your Koha instance database:


sudo koha-mysql demo

Sometimes, you may need to restart the Koha worker as well:


sudo koha-worker --restart demo

Remember, installing Koha is only the first step. You will also need to do regular upgrades, updates, and troubleshooting for both Koha and your Ubuntu Server operating system. If, however, you find the process too complex or time-consuming, consider hosting your library system with KohaSupport, a leading and trusted provider of Koha library management system support and services. If you are already running Koha or another library system, we will help you migrate your data so you can easily pick up where you left off. Get in touch with us today.