How to Install Koha Library System on Ubuntu Server 20.04 LTS
Koha integrated library system is the world’s first and the most popular open source library software in the world. It is used by thousands of libraries around the globe, from small libraries with a few hundred books to institutions with mega-catalogs in the hundreds of thousands hundred such as New York University. This is unsurprising because it is more cost-effective than commercial options such as Symphony, Millenium and Horizon while delivering enterprise-class features, modules, and performance.
To give you some perspective, 25 licenses of Sierra with a maximum of 100,000 items in the catalogue will set you back more than $1 million plus more than $170,000 for support services. Koha library system, on the other hand, will cost you somewhere between $0 (if you choose to self-host) to ~$2,500 per year with no limitations to the number of users, items, branches or patrons. You also get all the features you need to run your library, and many more that you don’t, including modules for circulation, cataloging, acquisitions, SQL reports and more.
Since you are reading this article, I am probably preaching to the choir and you’ve already decided to install Koha and try it out for yourself. Whether you are tinkering around or looking to setup a production server, you’ve come to the right place! If you decide that self-hosting isn’t the right option for you, the consider getting Koha cloud hosting with free tech support from Koha Support.

How to Install Koha Library System on Ubuntu Server 20.04 LTS

Koha integrated library system is the world’s first and the most popular open source library software in the world. It is used by thousands of libraries around the globe, from small libraries with a few hundred books to institutions with mega-catalogs in the hundreds of thousands hundred such as New York University. This is unsurprising because it is more cost-effective than commercial options such as Symphony, Millenium and Horizon while delivering enterprise-class features, modules, and performance.
To give you some perspective, 25 licenses of Sierra with a maximum of 100,000 items in the catalogue will set you back more than $1 million plus more than $170,000 for support services. Koha library system, on the other hand, will cost you somewhere between $0 (if you choose to self-host) to ~$2,500 per year with no limitations to the number of users, items, branches or patrons. You also get all the features you need to run your library, and many more that you don’t, including modules for circulation, cataloging, acquisitions, SQL reports and more.
Since you are reading this article, I am probably preaching to the choir and you’ve already decided to install Koha and try it out for yourself. Whether you are tinkering around or looking to setup a production server, you’ve come to the right place! If you decide that self-hosting isn’t the right option for you, the consider getting Koha cloud hosting with free tech support from Koha Support.
How to install Koha library system on Ubuntu Server 20.04 LTS
1. Prerequisites.
– A server running a fresh installation of Ubuntu Server 20.04LTS.
– SSH access to your server. You will be running all the following commands via the terminal.
– Your preferred text editor – I suggest nano but you can use anything you’re comfortable with.
– 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. You should not be doing this on a production server with other software running on it. That’s a bad idea. I suggest you try 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 it is you are doing first 🙂
2. Add the Koha community repository to your sources.
echo deb https://debian.koha-community.org/koha stable main | sudo tee /etc/apt/sources.list.d/koha.list
3. Add the Koha GPG Key.
wget -O- https://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
4. Update and upgrade your server.
sudo apt install update
sudo apt install upgrade
sudo apt clean
5. Install the latest Koha Release.
sudo apt install koha-common
6. Install Apache web server if you haven’t already.
sudo apt install apache2
7. Install MySQL or MariaDB server (either works fine).
sudo apt install mysql-server
for MySQL, or
sudo apt install mariadb-server
for MariaDB.
8. 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 (it’s the same command even if you are running MariaDB) to get started and follow the instructions – they are fairly straightfoward, answer “n” (for no) for the first question and “Y” (the default, yes) for the rest. If you need more guidance, follow the steps here:
sudo mysql_secure_installation
9. Enable the Apache mod_rewrite modules.
The following commands enable Apache to create the configuration files.
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.
10a. 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 the same name as your instance name (the one you used above)
sudo nano /etc/apache2/sites-available/demo.conf
Your config file will contain configurations similar to what’s 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, I 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 I use opac.example.com for the OPAC and staff.example.com for the Staff page.
– Add a ServerAlias for both domain/subdomain in both sections. This will ensure Apache will direct users to your instance whether they include or neglect the “www” when they type in your domain.
# OPAC
<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>
10b. Configure your server for a 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, I’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 nano /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 nano /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:
Enter your username and password and follow the prompts. They should be fairly straightforward. I will write another step-by-step article on how to complete the web setup soon, so make sure you subscribe to the newsletter to get the latest updates.
15. Troubleshooting
If you get Error 500 or other errors, try the following:
- – Make sure your Koha instance is enabled. Run
sudo koha-enable demo
- – Make sure Zebra is running. Run
sudo koha-zebra --start demo
- – Make sure Plack is running. Run
sudo koha-plack --enable demo
andsudo koha-plack --start demo
I hope found these instructions helpful! If you have any problems, let me know in the comments section below and I’ll be happy to help you out. Installing Koha library system is fairly complex and requires a good knowledge of Linux server platforms and applications like Apache, MySQL/MariaDB, Plack etc. 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. I will post more how-tos to help you with this so make sure you subscribe to the newsletter and follow Koha Support on Facebook, LinkedIn, Twitter and Youtube.
If however, you find the process too complex or time-consuming, consider hosting your Koha library with Koha Support for only $999 per year and comes with free tech support including updates, upgrades and troubleshooting. You won’t need to purchase servers or download any special software. And if you are already running Koha or another library system, I will migrate your data to your new server so you can easily pick up where you left off. Get a quote now and take advantage of a limited-time $100 discount for your first year of hosting.
7 Reasons Why You Need an Integrated Library Management System
Running a library isn’t as simple and straightforward as many people I have encountered think. It’s more than just checking out books and putting them back on the shelf when they are returned. Librarians have to deal other complex, time-consuming responsibilities like acquisitions, cataloguing, inventory, budgets, reports and interlibrary loaning. Pen and paper won’t cut it, and using an excel spreadsheet is only marginally better than digging a trench using a caviar spoon.
Koha Hacks: How to Install the Koha Offline Circulation Plugin
What do you do if your Koha library system suddenly goes offline due to a server crash, power or internet outage? Go back to the dark ages and start writing with pen and paper? Surely not! Koha has a very useful feature called Offline Circulation which allows you to...
How to Quickly Backup Your Koha Database
Regular backups of Koha are a must, in case your installation fails or your hardware crashes. While you should have an automated backup procedure in place, sometimes (before a major upgrade for example) you may need to make a quick one-time backup. So here's how to...
10 Things Every Librarian Should Do
Are you new to the librarian profession? Or you just need a quick refresher? This is the article for you.
[Solved] How to Backup Your Koha Library System MySQL Database
How to backup a MySQL database, including Koha
Koha Hacks: Why You Should Use Content Delivery Network (CDN) For Koha Library System
Is your Koha server taking too long to catalog or checkout items? Before you break the bank and purchase a bigger server with bucket-loads of RAM and processing power, you should try setting up a content delivery network (CDN) using a free service like CloudFlare...
Koha Hacks: How To Enable Apache Caching On A Koha Library System Server (running Ubuntu 20.04LTS)
Is your Koha server taking too long to catalog or checkout items? Before you break the bank and purchase a bigger server with bucket-loads of RAM and processing power, enable Apache caching on your Koha ILS server instead - you might just save yourself a lot of time...
Koha Hacks: How to Enable Plack on Koha Library System (Running On Ubuntu 20.04LTS)
Is your Koha server taking too long to catalog or checkout items? Before you break the bank and purchase a bigger server with bucket-loads of RAM and processing power, enable Plack instead - It will make your server much faster, and you might just save yourself a lot...
Koha Hacks: How to Install Memcached on Koha Library System (Running On Ubuntu 20.04LTS)
Is your Koha server taking too long to catalog or checkout items? Before you break the bank and purchase a bigger server with bucket-loads of RAM and processing power, install Memcached instead - you might just save yourself a lot of time and money! Is your Koha...
Koha Hacks: 4 Tricks To Supercharge Koha Library System (Running On Ubuntu 20.04LTS)
Is your Koha server taking too long to catalog or checkout items? Before you break the bank and purchase a bigger server with bucket-loads of RAM and processing power, try out the following tune-ups instead - you might just save yourself a lot of time and money!Is...
The Top 10 Biggest Libraries in the World
Libraries comes in all types and sizes, from small community libraries that open for a few hours once a week to mega institutions that operate 24 hours a day, 7 days a week. So which are the biggest, most impressive libraries in the world - by catalog size of course;...
Cage Match: Koha Library System vs Athenaeum
If you are shopping around for a new library software, you may have come across Koha and Athenaeum in your web searches. I hope you will find this article helpful as you compare the two and try to make a decision. Despite the Greek sounding name of Athenaeum, both...