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.
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.
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.
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:
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.
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.
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:
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.
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:
From Synaptic choose the Mark Packages by Task option:
Select LAMP Server:
Then click the “apply changes” checkmark:
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.
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.
Next give your web server a name. To do this, access the terminal console and enter this command to edit the Apache configuration file:
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
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.
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: http://wiki.koha.org/doku.php?id=encodingscratchpad
IMPORTANT: You _MUST_ follow all the steps outlined there for Apache2, MySQL 5, etc. BEFORE you install Koha.
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.
Enter the following at a command line prompt to install the required libraries:
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.
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.
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:
Once you reach the login page you’ll need to log in as a user with root privileges.
Part 3: Koha Prerequisites