Install Koha on Ubuntu — Part 2: Preparing Linux

Koha Logo

Warn­ing: this tuto­r­i­al was devel­oped in 2008, and is for ver­sions of Koha and Ubun­tu that are now con­sid­ered quite old. If you want to install the cur­rent ver­sion of Koha on Ubun­tu, please vis­it Koha on Ubun­tu at the Koha Com­mu­ni­ty wiki.

This is part 2 of 6 in a tuto­r­i­al series on installing Koha 3.0 on Ubun­tu 8.10.

This arti­cle cov­ers the ini­tial set­up of your Lin­ux serv­er before you start work­ing with Koha itself: installing Ubun­tu Lin­ux, web serv­er soft­ware (Apache), data­base serv­er soft­ware (MySQL), and an admin­is­tra­tion util­i­ty (Web­min).

If you plan to put Koha into pro­duc­tion for real-world Library use there are many oth­er things you need to con­sid­er. The final arti­cle in the series, Going Live, dis­cuss­es this fur­ther.

Who this arti­cle is for.
  • Peo­ple who want to try Koha.
  • Peo­ple who aren’t nec­es­sar­i­ly Lin­ux experts, but…
  • Who are very com­fort­able with com­put­ers and not afraid of using a com­mand-line inter­face.
What to expect.

Step 1: Install Ubuntu 8.10

This install guide assumes you are using a fresh­ly installed Ubun­tu 8.10 sys­tem. If you’re using an exist­ing Ubun­tu sys­tem that has oth­er soft­ware installed, or are using a Lin­ux dis­tro oth­er than Ubun­tu, some of the steps in this guide will be dif­fer­ent.

If you haven’t installed Ubun­tu yet you can down­load it from the Ubun­tu web­site. Once you’ve down­loaded the Ubun­tu 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 Ubun­tu. You’ll find instruc­tions on installing Ubun­tu at the Offi­cial Ubun­tu 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 com­mand-line shell prompt. You can access the shell via the GNOME Ter­mi­nal util­i­ty: Appli­ca­tions > Acces­sories > Ter­mi­nal.

Optional: Configure a Shortcut 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 quick­ly. 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­to­ry 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­to­ry is mea­ger, so it’s worth increas­ing it. From with­in 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 his­to­ry.

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: Create a LAMP Server

The next step is to set up your Ubun­tu machine as a Lin­ux, Apache, MySQL, and PHP (LAMP) serv­er. Koha requires this foun­da­tion of sys­tem ser­vices.

Update Ubuntu

Before going any fur­ther you should patch your machine with the lat­est updates. Ubun­tu checks for updates auto­mat­i­cal­ly, 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:

Screenshot of Linux Update Region

Updat­ing Lin­ux

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

Selecting Ubuntu's Update Manager

Select­ing Ubuntu’s Update Man­ag­er

Install LAMP Support

After updat­ing Ubun­tu, restart Lin­ux before installing LAMP.

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

Selecting the Synaptic package manager

Select­ing the Synap­tic pack­age man­ag­er

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

Marking packages by task in Synaptic

Mark­ing pack­ages by pask in Synap­tic

Select LAMP Serv­er:

Selecting LAMP software in Synaptic

Select­ing LAMP soft­ware in Synap­tic

Then click the “apply changes” check­mark:

Applying changes to install the LAMP software

Apply­ing changes to install the LAMP soft­ware

As part of the instal­la­tion process Ubun­tu will prompt you for a pass­word for the MySQL root user. (The user account you cre­ate this way won’t be a Lin­ux 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 lat­er.

When the instal­la­tion fin­ish­es, your Ubun­tu machine will be an Apache web serv­er sup­port­ing PHP, and a MySQL data­base serv­er.

Configure 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 lev­el of priv­i­leges, aka root access. If you only cre­at­ed one user when you installed Ubun­tu, that user is your root user.

sudo su

Next give your web serv­er 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 serv­er.

#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 mes­sages.

/etc/init.d/apache2 restart

Final­ly, if you want to be sure your sys­tem will prop­er­ly sup­port multi­na­tion­al 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­pos­es of set­ting up a demon­stra­tion Koha serv­er 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

Web­min is a fea­ture-rich, web-based appli­ca­tion that lets you man­age an impres­sive vari­ety of things on your system—from basic Lin­ux 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 anoth­er con­fig­u­ra­tion man­ag­er, that’s fine. Web­min is a good choice oth­er­wise.

Install Webmin

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­to­ry 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 lat­er ver­sion you cer­tain­ly may.

cd /
mkdir build
cd build
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 Webmin

You can use https://localhost:10000 when you’re logged into the serv­er itself. The first time you vis­it the site from a giv­en com­put­er, the brows­er 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­mal­ly a good and help­ful thing. It means your brows­er is try­ing to pre­vent you from inad­ver­tent­ly trust­ing an unknown but evil per­son. In this case the mes­sage isn’t use­ful since the web serv­er 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 fol­lows:

  1. Click “Or you can add an excep­tion…” in the mes­sage.
  2. Click the “Add Excep­tion” but­ton.
  3. Click the “Get Cer­tifi­cate” but­ton.
  4. Click the “Con­firm Secu­ri­ty Excep­tion” but­ton.

Once you reach the login page you’ll need to log in as a user with root priv­i­leges.

Next Section…

Part 3: Koha Pre­req­ui­sites

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