Install Koha on Ubuntu — Part 2: Preparing Linux

Warn­ing: this tuto­r­ial was devel­oped in 2008, and is for ver­sions of Koha and Ubuntu that are now con­sid­ered quite old. If you want to install the cur­rent ver­sion of Koha on Ubuntu, please visit Koha on Ubuntu at the Koha Com­mu­nity wiki.

This is part 2 of 6 in a tuto­r­ial series on installing Koha 3.0 on Ubuntu 8.10.

This arti­cle cov­ers the ini­tial setup of your Linux server before you start work­ing with Koha itself: installing Ubuntu Linux, web server soft­ware (Apache), data­base server soft­ware (MySQL), and an admin­is­tra­tion util­ity (Webmin).

If you plan to put Koha into pro­duc­tion for real-world Library use there are many other things you need to con­sider. The final arti­cle in the series, Going Live, dis­cusses this further.

Step 1: Install Ubuntu 8.10

This install guide assumes you are using a freshly installed Ubuntu 8.10 sys­tem. If you’re using an exist­ing Ubuntu sys­tem that has other soft­ware installed, or are using a Linux dis­tro other than Ubuntu, some of the steps in this guide will be different.

If you haven’t installed Ubuntu yet you can down­load it from the Ubuntu web­site. Once you’ve down­loaded the Ubuntu CD you’ll need to use a soft­ware pack­age like InfraRecorder to burn the CD image file (.iso file) to a CD. Once that’s done you can install Ubuntu. You’ll find instruc­tions on installing Ubuntu at the Offi­cial Ubuntu Doc­u­men­ta­tion site.

Access the Linux Shell

You’ll per­form most of the steps of this instal­la­tion at a command-line shell prompt. You can access the shell via the GNOME Ter­mi­nal util­ity: Appli­ca­tions > Acces­sories > Terminal.

Optional: Con­fig­ure a Short­cut for Terminal

As you install and con­fig­ure Koha you’ll spend a good bit of time in the ter­mi­nal, so it’s worth set­ting up a way to launch it quickly. To do this you can either:

1. Go to the Appli­ca­tions > Acces­sories and drag the Ter­mi­nal icon up to the menu bar at the top of the screen.
2. Go to Sys­tem > Pref­er­ences > Key­board Short­cuts, scroll down and click on “Run a Ter­mi­nal”, then press a key­press com­bi­na­tion that will launch ter­mi­nal for you. This is my pre­ferred approach. I use Shift-Ctrl-Alt-D for “DOS Prompt”, which I sup­pose both dates me and telegraphs my tech­ni­cal back­ground. For that mat­ter using the word “tele­graph” prob­a­bly dates me too.

Optional: Increase the Terminal’s Scroll History

Often it can be use­ful to scroll back through the his­tory of your ter­mi­nal win­dow to see what hap­pened, or to copy and paste text so you can email it to oth­ers for help. By default the ter­mi­nal window’s scroll his­tory is mea­ger, so it’s worth increas­ing it. From within the Ter­mi­nal appli­ca­tion go to: Edit > Pro­file Pref­er­ences > Scrolling tab > set the Scroll­back to at least 20,000 lines. This might sound like a lot, but a com­plete Koha instal­la­tion can gen­er­ate well over 50,000 lines of scroll-back history.

And no, that’s not a typo: fifty thou­sand lines of com­mand line entries and diag­nos­tic mes­sages. Get­ting ner­vous yet? Take a few deep breaths. It’ll be ok.

Step 2: Cre­ate 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 foun­da­tion of sys­tem services.

Update Ubuntu

Before going any fur­ther you should patch your machine with the lat­est updates. Ubuntu checks for updates auto­mat­i­cally, so by this time you might see a red “updates avail­able” arrow in the upper right cor­ner of the screen. If so click it:

Updat­ing Linux

Oth­er­wise you can invoke the update man­ager man­u­ally, installing all avail­able updates. Once you open the Update Man­ager it might say “Your sys­tem is up to date” but you can’t nec­es­sar­ily believed that. You need to make it check for avail­able updates first by click­ing the “Check” but­ton. Then install all updates.

Select­ing Ubuntu’s Update Manager

Install LAMP Support

After updat­ing Ubuntu, restart Linux before installing LAMP.

One easy way to install LAMP sup­port is to use the Synap­tic Pack­age Man­ager. Synap­tic lets you install an aston­ish­ing array of free soft­ware. You can access it from Sys­tem > Administration:

Select­ing the Synap­tic pack­age manager

From Synap­tic choose the Mark Pack­ages by Task option:

Mark­ing pack­ages by pask in Synaptic

Select LAMP Server:

Select­ing LAMP soft­ware in Synaptic

Then click the “apply changes” checkmark:

Apply­ing changes to install the LAMP software

As part of the instal­la­tion process Ubuntu will prompt you for a pass­word for the MySQL root user. (The user account you cre­ate this way won’t be a Linux user account but a MySQL user account.) Remem­ber your pass­word since you’ll need to pro­vide MySQL root login infor­ma­tion later.

When the instal­la­tion fin­ishes, your Ubuntu machine will be an Apache web server sup­port­ing PHP, and a MySQL data­base server.

Con­fig­ure the Apache Web Server

We need to make a few small changes to the web server’s con­fig­u­ra­tion. Open a ter­mi­nal ses­sion and sign is as a superuser—a user with the high­est level of priv­i­leges, aka root access. If you only cre­ated 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 ter­mi­nal con­sole and enter this com­mand to edit the Apache con­fig­u­ra­tion file:

gedit /etc/apache2/apache2.conf

Once you are in the edi­tor add these lines to the top of the file then save and exit. Replace Your­Site­Name with the name you want to give this Koha server.

#Define the server's name
ServerName "YourSiteName"

These lines will pre­vent a benign error mes­sage when restart­ing Apache. Enter the fol­low­ing com­mands to restart Apache 2 and accept the new set­tings. If all went well you should see no error messages.

/etc/init.d/apache2 restart

Finally, if you want to be sure your sys­tem will prop­erly sup­port multi­na­tional char­ac­ter sets through Uni­code, the Koha instal­la­tion instruc­tions include the fol­low­ing note.

If you’re not con­cerned about this for pur­poses of set­ting up a demon­stra­tion 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.

Step 3: Set up An Admin­is­tra­tion Dashboard

Web­min is a feature-rich, web-based appli­ca­tion that lets you man­age an impres­sive vari­ety of things on your system—from basic Linux func­tions like back­ups and user man­age­ment, to sys­tem ser­vices like MySQL. If you’re com­fort­able using the com­mand line for these things, or if you pre­fer another con­fig­u­ra­tion man­ager, that’s fine. Web­min is a good choice otherwise.

Install Web­min

Enter the fol­low­ing at a com­mand 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 down­load and install Web­min. If the /build direc­tory already exists, the mkdir build com­mand will give you a “File exists” error; you may ignore it. Also, this guide has been writ­ten for Web­min 1.441 but if you’d like to install a later ver­sion you cer­tainly may.

cd /
mkdir build
cd build
wget http://downloads.sourceforge.net/webadmin/webmin_1.441_all.deb
dpkg -i webmin_1.441_all.deb

At the end you’ll see a mes­sage 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 Web­min

You can use https://localhost:10000 when you’re logged into the server itself. The first time you visit the site from a given com­puter, the browser will give you a warn­ing mes­sage. For Fire­fox it’ll look some­thing 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 some­thing nefar­i­ous is about to hap­pen. This mes­sage is nor­mally a good and help­ful thing. It means your browser is try­ing to pre­vent you from inad­ver­tently trust­ing an unknown but evil per­son. In this case the mes­sage isn’t use­ful since the web server you’re being asked to trust is your own.

If you your­self are an evil per­son then there’s cause for con­cern. Oth­er­wise you can work around the error as follows:

1. Click “Or you can add an excep­tion…” in the message.
2. Click the “Add Excep­tion” button.
3. Click the “Get Cer­tifi­cate” button.
4. Click the “Con­firm Secu­rity Excep­tion” button.

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

Next Sec­tion…

Part 3: Koha Pre­req­ui­sites