How To Install Koha Library Software On An Ubuntu 12.04 x32 VPS

Status: Deprecated

This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:

• Upgrade to Ubuntu 14.04.
• Upgrade from Ubuntu 14.04 to Ubuntu 16.04
• Migrate the server data to a supported version

Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.

See Instead:
This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.

What is the Koha Library Software?

Koha Library Software is a ILS or Integrated Library System that is used in thousands of Libraries around the world. It is mature and has been in active development for over 10 years.

This article will go over two separate methods for setup of public access, you can choose 4a or 4b.

Let’s Start by spinning up a Ubuntu 12.04 x32 VPS!

Step 1: Access your Server

SSH over to your server:

ssh root@{your server's ip address here} 

and Login.

Step 2: Add the Koha Repositories to Ubuntu Sources.List

Once you are logged in to your VPS run the following commands, these will add the Koha Repositories to the Ubuntu Sources list:

echo deb http://debian.koha-community.org/koha squeeze main | sudo tee /etc/apt/sources.list.d/koha.list
wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get upgrade
sudo apt-get clean

These commands do the following:

• Add the Koha Respitory to the Ubuntu sources
• Add the Koha Key to Ubuntu
• Update the package list

Step 3: Install Koha

Now let’s get the Koha package and install it!

Run the Following command:

apt-get install koha-common

This command will install Koha along with any dependencies it requires. It will prompt you for more information about mail servers, configure the first prompt with the Fully Qualified Domain name (or localhost if you are using an IP address to access the server).

Step 4a: Configure Koha for Web Access with an IP address

This step shows you how to configure Koha with access though an IP address, if you are using a Domain Name, skip to Step 4b. Access the Koha Config file by typing the following command:

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

You should see the following. If not, add this to the file:

DOMAIN=""  # Change this to be your domain. Any instance will be a subdomain of this string.
INTRAPORT="8080"  # 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'

This config file says the the Staff Interface can be accessed at [YOUR IP ADDRESS]:8080 and the OPAC can be accessed at [YOUR IP ADDRESS]:80.

Step 4b: Configure Koha for Web Access with a Domain

This step shows how to configure Koha with a domain for web access if you followed step 4a, skip this step and continue on to step 5. Please make sure that you have both a WILDCARD (*.yourlibrary.com) pointing to this VPS in addition to yourlibrary.com. You can see how to achieve that here.

Access the Koha Config file by typing the following command:

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

You should see the following, if not add this to the file:

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'

Make the following changes (they are in blue):

DOMAIN=".yourlibrary.com"  # 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'

This config file says the the Staff Interface can be accessed at: [InstanceName].yourlibrary.com and the OPAC can be accessed at [InstanceName].yourlibrary.com.

Step 5: Setup the Database and Apache

If MySQL is not already installed, issue the following at the command line:

sudo apt-get install mysql-server

The VPS will prompt for a password twice, set this to something different than the server password

Now, enable mod_rewrite on apache by entering the following commands:

a2enmod rewrite
service apache2 restart

Time to create your Koha instance! Issue the following commands at the command line:

koha-create --create-db [YOUR INSTANCE NAME HERE]

What ever you choose is the subdomain where you will access your OPAC. For example, if I choose library I will access my OPAC at Library.MyLibrary.com.

Step 6: Secure Mysql

MySQL Allow anonymous connections, which is a security no-no. Access the MySQL server by typing:

mysql -u root -p

Then Enter your MySQL root password. Then issue the following commands:

USE mysql;
SELECT host,user FROM user;
DELETE FROM user WHERE user='';
SELECT host,user FROM user;
FLUSH PRIVILEGES;
QUIT

Step 7: Enable the Site and Apache Mods

Access the Apache Ports.conf by typing:

nano /etc/apache2/ports.conf

Find the line that says:

#Listen 80

and change it to:

Listen 80

Make sure the following line is uncommented (no #):

NameVirtualHost *:80

Now run the following commands replacing [YOUR INSTANCE] with the instance name you chose earlier:

sudo a2enmod deflate
sudo a2ensite [YOUR INSTANCE]
sudo service apache2 restart

Step 8: Configure Koha from the Web

First, get your password:

sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/[YOUR INSTANCE NAME]/koha-conf.xml

The Username is koha_[INSTANCE NAME]. Now in your web browser's address bar, enter:

if you followed step 4a:
[YOUR IP ADDRESS]:8080
if you followed step 4b:
[YOUR INSTANCE NAME]-[YOUR DOMAIN] eg.koha.mydomain.com

Then enter the username and password from earlier. Simply follow the instructions in the web browser to finish the install!

More Information

More information about Koha can be found at: http://koha-community.org. Documentation can be found at: http://wiki.koha-community.org/wiki/Category:Documentation.