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 and sudo koha-plack --start demo