Install Koha on Ubuntu — Part 2: Preparing Linux

Koha Logo

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.

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

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:

Screenshot of Linux Update Region

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.

Selecting Ubuntu's Update Manager

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:

Selecting the Synaptic package manager

Select­ing the Synap­tic pack­age manager

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

Marking packages by task in Synaptic

Mark­ing pack­ages by pask in Synaptic

Select LAMP Server:

Selecting LAMP software in Synaptic

Select­ing LAMP soft­ware in Synaptic

Then click the “apply changes” checkmark:

Applying changes to install the LAMP software

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

There are 11 responses to this post.

By Kazi on December 25, 2010 at 11:49 pm

Dear Sir,

Koha requires which ver­sion of Ubuntu/ Debian for suit­able instal­la­tion—- Desk­top ver­sion or Server Edition?

The sec­ond one is that the demo here shown is Server edi­tion of Ubuntu 8.10 or Desk­top edi­tion of Ubuntu 8.10.

Would you please clar­ify me?

I do not find Lamp server in any of the Desk­top version.

Thanks.

Unknown

 

By Andy on January 3, 2011 at 4:38 pm

I apol­o­gize for the delay, Kazi. I’ve been away from work for a cou­ple of weeks and am just catch­ing up.

Although I’m sure it’s pos­si­ble to install Koha on the Server edi­tion of Ubuntu, I don’t rec­om­mend it unless you’re a Linux expert.

The server edi­tion lacks a GUI (graph­i­cal windows-based) inter­face. Linux experts will be very com­fort­able run­ning every­thing from the com­mand line, but a GUI makes cer­tain man­age­ment tasks eas­ier for non-experts. This tuto­r­ial was writ­ten using the desk­top edition.

By henry on May 24, 2011 at 11:53 pm

i’m new to koha and ubuntu. your guid­lines have being very help­ful to me but i’m stuck try­ing to set up my own locale and the link( http://wiki.koha.org/doku.php?id=encodingscratchpad) can not be found on the inter­net. must i do this before installing Koha? i will appre­ci­ate if you can send guid­lines on how to set locale.

 

By Andy on May 25, 2011 at 9:00 am

Hi Henry,

When I worked up this instal­la­tion guide I didn’t need to sup­port multi­na­tional char­ac­ter sets through Uni­code. If you plan to use Koha in the same way (using English/Latin char­ac­ter sets) you don’t need to fol­low those addi­tional instructions.

If you do need to sup­port multi­na­tional char­ac­ter sets, unfor­tu­nately I don’t have the expe­ri­ence to help. I’d rec­om­mend Googling for Koha Uni­code sup­port; there might be blogs or forums with advice. Best of luck.

By SAMUEL MABUSIO on July 4, 2011 at 12:53 am

must i be linux expert to use koha?

By SAMUEL MABUSIO on July 4, 2011 at 12:56 am

am library assis­tant work­ing in a uni­ver­sity institution,i have a library clien­tele of about 2500.how is koha gonna help me con­trol and man­age my cli­en­tile effec­tively with easy?

 

By Andy on July 5, 2011 at 9:56 am

Hi Samuel,

You don’t need to be an expert to install Koha for test­ing pur­poses. How­ever, as I dis­cuss in Part 6 “Going Live” (http://www.blazingmoon.org/news/2008/12/install-koha-on-ubuntu-part-6-going-live/), I rec­om­mend that you get help from a Linux pro­fes­sional if you want to set up Koha for real use.

As for how it will help with your spe­cific library, since my use of Koha is very limited–primarily installing and con­fig­ur­ing it–the Koha Com­mu­nity will be able to give you much bet­ter answers than I can: http://koha-community.org/support/forums/.

By John Elkington on July 27, 2011 at 4:14 am

I am about to try and install KOHA for a client — and although I’m a web designer / PHP pro­gram­mer and famil­iar with cPanel, I’m wholly unfa­mil­iar with Linux. For this project, I intend to set up VPS host­ing, which comes with Linux Cen­tOS 5x, Debian5, Fedora Core 10 and Ubuntu 9x — and it also comes with Vir­tuozzo, which, I gather, pro­vides an inter­face. Before I take the plunge, can I assume that this excel­lent guide of yours will be appro­pri­ate for the lat­est KOHA release — and do I need to spec­ify any con­fig­u­ra­tion require­ments when set­ting up the host­ing?
I’be be most grate­ful for advice — and thanks in antic­i­pa­tion.
John

By SAMUEL MABUSIO on November 25, 2011 at 9:34 am

Am samuel mabu­sio Pwani uni­ver­sity cir­cu­la­tion department.am really impressed how easy and man­age­able it is to use Koha cir­cu­la­tion module.time for issu­ing and receiv­ing of items to and from users has really been reduced among others.am able to serve 50 uni­ver­sity library users within 10 min­utes only– no queues,no stress.check– ins-checkouts pap!

By Kazi on December 13, 2011 at 7:12 am

I apol­o­gize for the delay and grate­ful as well, Andy. Actu­ally I saw the reply after almost a year finished.I saw it today, though I installed koha on Debian successfully.Thank you for your favour.

By Install Koha on Ubuntu — Part 1: Introduction » Blazing Moon on July 30, 2012 at 4:08 pm

[…] Part 2: Prepar­ing Linux […]

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