Install Koha on Ubuntu — Part 2: Preparing Linux

Koha Logo

Warning: this tutorial was developed in 2008, and is for versions of Koha and Ubuntu that are now considered quite old. If you want to install the current version of Koha on Ubuntu, please visit Koha on Ubuntu at the Koha Community wiki.

This is part 2 of 6 in a tutorial series on installing Koha 3.0 on Ubuntu 8.10.

This article covers the initial setup of your Linux server before you start working with Koha itself: installing Ubuntu Linux, web server software (Apache), database server software (MySQL), and an administration utility (Webmin).

If you plan to put Koha into production for real-world Library use there are many other things you need to consider. The final article in the series, Going Live, discusses this further.

Who this article is for.
  • People who want to try Koha.
  • People who aren’t necessarily Linux experts, but…
  • Who are very comfortable with computers and not afraid of using a command-line interface.
What to expect.

Step 1: Install Ubuntu 8.10

This install guide assumes you are using a freshly installed Ubuntu 8.10 system. If you’re using an existing Ubuntu system that has other software installed, or are using a Linux distro other than Ubuntu, some of the steps in this guide will be different.

If you haven’t installed Ubuntu yet you can download it from the Ubuntu website. Once you’ve downloaded the Ubuntu CD you’ll need to use a software package like InfraRecorder to burn the CD image file (.iso file) to a CD. Once that’s done you can install Ubuntu. You’ll find instructions on installing Ubuntu at the Official Ubuntu Documentation site.

Access the Linux Shell

You’ll perform most of the steps of this installation at a command-line shell prompt. You can access the shell via the GNOME Terminal utility: Applications > Accessories > Terminal.

Optional: Configure a Shortcut for Terminal

As you install and configure Koha you’ll spend a good bit of time in the terminal, so it’s worth setting up a way to launch it quickly. To do this you can either:

  1. Go to the Applications > Accessories and drag the Terminal icon up to the menu bar at the top of the screen.
  2. Go to System > Preferences > Keyboard Shortcuts, scroll down and click on “Run a Terminal”, then press a keypress combination that will launch terminal for you. This is my preferred approach. I use Shift-Ctrl-Alt-D for “DOS Prompt”, which I suppose both dates me and telegraphs my technical background. For that matter using the word “telegraph” probably dates me too.

Optional: Increase the Terminal’s Scroll History

Often it can be useful to scroll back through the history of your terminal window to see what happened, or to copy and paste text so you can email it to others for help. By default the terminal window’s scroll history is meager, so it’s worth increasing it. From within the Terminal application go to: Edit > Profile Preferences > Scrolling tab > set the Scrollback to at least 20,000 lines. This might sound like a lot, but a complete Koha installation can generate well over 50,000 lines of scroll-back history.

And no, that’s not a typo: fifty thousand lines of command line entries and diagnostic messages. Getting nervous yet? Take a few deep breaths. It’ll be ok.

Step 2: Create a LAMP Server

The next step is to set up your Ubuntu machine as a Linux, Apache, MySQL, and PHP (LAMP) server. Koha requires this foundation of system services.

Update Ubuntu

Before going any further you should patch your machine with the latest updates. Ubuntu checks for updates automatically, so by this time you might see a red “updates available” arrow in the upper right corner of the screen. If so click it:

Screenshot of Linux Update Region

Updating Linux

Otherwise you can invoke the update manager manually, installing all available updates. Once you open the Update Manager it might say “Your system is up to date” but you can’t necessarily believed that. You need to make it check for available updates first by clicking the “Check” button. Then install all updates.

Selecting Ubuntu's Update Manager

Selecting Ubuntu's Update Manager

Install LAMP Support

After updating Ubuntu, restart Linux before installing LAMP.

One easy way to install LAMP support is to use the Synaptic Package Manager. Synaptic lets you install an astonishing array of free software. You can access it from System > Administration:

Selecting the Synaptic package manager

Selecting the Synaptic package manager

From Synaptic choose the Mark Packages by Task option:

Marking packages by task in Synaptic

Marking packages by pask in Synaptic

Select LAMP Server:

Selecting LAMP software in Synaptic

Selecting LAMP software in Synaptic

Then click the “apply changes” checkmark:

Applying changes to install the LAMP software

Applying changes to install the LAMP software

As part of the installation process Ubuntu will prompt you for a password for the MySQL root user. (The user account you create this way won’t be a Linux user account but a MySQL user account.) Remember your password since you’ll need to provide MySQL root login information later.

When the installation finishes, your Ubuntu machine will be an Apache web server supporting PHP, and a MySQL database server.

Configure the Apache Web Server

We need to make a few small changes to the web server’s configuration. Open a terminal session and sign is as a superuser—a user with the highest level of privileges, aka root access. If you only created one user when you installed Ubuntu, that user is your root user.

sudo su

Next give your web server a name. To do this, access the terminal console and enter this command to edit the Apache configuration file:

gedit /etc/apache2/apache2.conf

Once you are in the editor add these lines to the top of the file then save and exit. Replace YourSiteName with the name you want to give this Koha server.

#Define the server's name
ServerName "YourSiteName"

These lines will prevent a benign error message when restarting Apache. Enter the following commands to restart Apache 2 and accept the new settings. If all went well you should see no error messages.

/etc/init.d/apache2 restart

Finally, if you want to be sure your system will properly support multinational character sets through Unicode, the Koha installation instructions include the following note.

If you’re not concerned about this for purposes of setting up a demonstration Koha server you can skip ahead.

1.2 Set up your locale
Your locale should be set to UTF-8, as should Apache2 and MySQL 5. This step is VERY IMPORTANT for a UNICODE compliant system. Please read over the following document carefully:
IMPORTANT: You _MUST_ follow all the steps outlined there for Apache2, MySQL 5, etc. BEFORE you install Koha.

Step 3: Set up An Administration Dashboard

Webmin is a feature-rich, web-based application that lets you manage an impressive variety of things on your system—from basic Linux functions like backups and user management, to system services like MySQL. If you’re comfortable using the command line for these things, or if you prefer another configuration manager, that’s fine. Webmin is a good choice otherwise.

Install Webmin

Enter the following at a command line prompt to install the required libraries:

sudo su
apt-get install libnet-ssleay-perl
apt-get install libauthen-pam-perl
apt-get install libio-pty-perl
apt-get install libmd5-perl
apt-get install openssl

Now download and install Webmin. If the /build directory already exists, the mkdir build command will give you a “File exists” error; you may ignore it. Also, this guide has been written for Webmin 1.441 but if you’d like to install a later version you certainly may.

cd /
mkdir build
cd build
dpkg -i webmin_1.441_all.deb

At the end you’ll see a message like this:

Webmin install complete. You can now login to https://[machinename]:10000/ as root with your root password, or as any user who can use sudo to run commands as root.

Access Webmin

You can use https://localhost:10000 when you’re logged into the server itself. The first time you visit the site from a given computer, the browser will give you a warning message. For Firefox it’ll look something like this:

Secure Connection Failed
[machinename]:10000 uses an invalid security certificate.
The certificate is not trusted because it is self signed.
(Error code: sec_error_untrusted_issuer).

…which sounds like something nefarious is about to happen. This message is normally a good and helpful thing. It means your browser is trying to prevent you from inadvertently trusting an unknown but evil person. In this case the message isn’t useful since the web server you’re being asked to trust is your own.

If you yourself are an evil person then there’s cause for concern. Otherwise you can work around the error as follows:

  1. Click “Or you can add an exception…” in the message.
  2. Click the “Add Exception” button.
  3. Click the “Get Certificate” button.
  4. Click the “Confirm Security Exception” button.

Once you reach the login page you’ll need to log in as a user with root privileges.

Next Section…

Part 3: Koha Prerequisites

Registration is required to comment.

You aren't currently logged in. You can use the fields below to post a comment without logging in or registering, or you can log in or register now.

By submitting a comment here you grant Blazing Moon a perpetual license to reproduce your words and name/web site in attribution. Inappropriate comments will be removed at admin's discretion.

Blazing Moon RSS Feed