Install Koha on Ubuntu — Part 5: Testing

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 5 of 6 in a tuto­r­i­al series on installing Koha 3.0 on Ubun­tu 8.10.

In the pre­ced­ing arti­cles we installed the ground­work for Koha and then installed Koha itself.

But so far you haven’t actu­al­ly used (or even seen) your new Koha sys­tem. This arti­cle will let you start play­ing with it.

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.

Configure Koha

Con­grat­u­la­tions! You’ve installed Koha.

Next we need to con­fig­ure it and enter a lit­tle test data to con­firm everything’s work­ing.

At this point you should still be using the web brows­er on the Koha serv­er itself rather than try­ing to access Koha from a dif­fer­ent com­put­er.

Open Fire­fox and open Koha’s admin­is­tra­tive front-end. If you’ve installed Koha on a fresh Ubun­tu instal­la­tion this should be

Web Installer > Step 1

The only ques­tion you’ll need to answer is your pre­ferred lan­guage. (Note: if you want Eng­lish and pick the default option uk-UA think­ing it has some­thing to do with the Unit­ed King­dom, get ready to use Koha in Cyril­lic since uk-UA means Ukrain­ian. You want “en” for Eng­lish.)

Web Installer > Step 2

You’ll be asked to review data­base set­tings and click Next if they’re cor­rect. If they’re not cor­rect you’ll need to edit the cor­rect con­fig­u­ra­tion file (usu­al­ly koha-config.xml). If all is well, after you click “Next” you’ll be told that a data­base con­nec­tion has been estab­lished and that your MySQL user has the right priv­i­leges.

Web Installer > Step 3

Click “Next”. You should see the mes­sage, “Suc­cess. Data­base tables cre­at­ed.”

Next click the “Install basic con­fig­u­ra­tion set­tings” hyper­link and select your pre­ferred MARC fla­vor.

Installing Optional Data

Install all the option­al exam­ple data. You can change it lat­er, but espe­cial­ly since this is a sam­ple Koha imple­men­ta­tion you’ll want some data to help you test the sys­tem.

Zebra or NoZebra?

Choose NoZe­bra. Zebra con­fig­u­ra­tion and trou­bleshoot­ing is beyond this guide’s scope (and also beyond mine). For a test serv­er Koha’s native search engine will do fine.

If all has gone well you’ll get the mes­sage, “Con­grat­u­la­tions, Instal­la­tion com­plete.”

Buy Two Books to Circulate

  1. When pre­sent­ed with the Koha login page, use your Koha administrator’s cre­den­tials (the ones you used above), log­ging into the Cen­ter­ville library.
  2. Click “Acqui­si­tions”.
  3. Click the “+ New Ven­dor” but­ton.
  4. Fill in at least the required details. Under “Order­ing Infor­ma­tion” click “Ven­dor is: Active”.
  5. Save.
  6. Click the “+ New Order” but­ton.
  7. Under “Add To Order” click “From a new (emp­ty) record”.
  8. Fill in the required details plus any oth­ers you’d like to include. Make the order for Cen­ter­ville branch. Order “Neu­ro­mancer” by author “Gib­son, William”. Order 2 copies, enter­ing 10 for the price. For the Invoice Num­ber enter 12345.
  9. Save.
  10. Click the “Close this bas­ket” link just above the Order Details.
  11. Click “Receive ship­ment” under “Order Receive” and enter your invoice num­ber: 12345.
  12. Save.
  13. In the bot­tom table (labeled “or select a pend­ing orders” [sic]), click the “Receive order” link next to your Neu­ro­mancer item.
  14. Enter a bar­code of 23456, tweak any­thing else you’d like to, and click [Save] to receive the first copy of the book for Cen­ter­ville.
  15. Repeat the process for the sec­ond copy, using a dif­fer­ent bar­code such as 34567.

Con­grat­u­la­tions! Your library now has two books to loan.

Give It a Test Drive

Now you can try the Koha OPAC as a patron rather than an admin­is­tra­tor. First we need to cre­ate a patron record.

Create a Patron Record

  1. Click the “Patrons” link at the top of the page.
  2. Click the “+ New” but­ton.
  3. Choose “Patron” from the drop-down that appears.
  4. Enter infor­ma­tion for your­self. Be sure to make your­self a patron of the Cen­ter­ville branch. Give your­self a library card num­ber of 1234567890. Also give your­self an OPAC Login (i.e., user­name) and a Pass­word.
  5. Click [Save] to cre­ate your record.

Find the Book as a Patron

  1. Click “Log Out” in the upper right cor­ner.
  2. Become a patron: switch to OPAC at
  3. Click “Log in to Your Account” in the upper right and enter the patron login cre­den­tials you cre­at­ed a moment ago.
  4. Search the cat­a­log for “Neu­ro­mancer”. You should see the two books you just acquired.

Check Out a Book for a Patron

Now let’s pre­tend we’re work­ing the circ desk and help­ing a patron to check out one of our two book.

  1. Click “Log Out” in the upper right cor­ner.
  2. Go back to the staff inter­face at
  3. Log in with the Koha Administrator’s user­name and pass­word. (In a pro­duc­tion sys­tem you wouldn’t log in as the pri­ma­ry Koha admin­is­tra­tor; each per­son work­ing the circ desk would have his or her own login.)
  4. In the upper right cor­ner, next to “NO_LIBRARY_SET”, click “Set” and choose Cen­ter­ville.
  5. In the field at the top enter the patron’s card num­ber (1234567890) or a par­tial name.
  6. At the “Enter item bar­code” field enter the bar­code num­ber of one of your books, for exam­ple, 23456.
  7. Spec­i­fy a due date. Koha requires ful­ly padded dates, i.e., “07/07/2009” rather than “7/7/2009”.
  8. Click the “Check Out” but­ton.

Check In and Review Circ History

Now let’s just rev­el in the fact that it all worked by look­ing at the patron’s record.

  1. Click the Patrons link at the top of the page.
  2. Search for the patron by name or card num­ber.
  3. In the table list­ing match­ing patrons, click the name of the one you want.
  4. Scroll to the bot­tom of the screen and notice that the patron does indeed have Neu­ro­mancer checked out.

Finally we can check in the book.

  1. Click “Cir­cu­la­tion” at the top of the page.
  2. Click “Check In” and check in item 23456.

Extra credit

  1. Click “Patrons” at the top of the page.
  2. Select your patron.
  3. Click the “Cir­cu­la­tion His­to­ry” tab at the left of the screen.
  4. Bask in the glow of Koha’s awe­some­ness.
  5. Bask in the glow of your own awe­some­ness, too.

Optional: MARC Import

Koha includes scripts to let you import MARC-for­mat­ted data from anoth­er sys­tem. You can import a file in ISO 2709 for­mat like this:

cd /usr/share/koha/bin/migration_tools
./ -file /pathtoISO2709file/filename

If you want to see help about the import script:

./ -h

If you’d pre­fer a web-based inter­face rather than the com­mand line you can find this fea­ture on the Koha Staff site (http://localhost:8080): click the “More” but­ton at the top of the screen then go to Tools > Stage MARC Records for Import.

Accessing Koha from Other Computers

Although you now have a work­ing Koha test bed, your con­fig­u­ra­tion will only let you use Koha from the com­put­er on which it’s installed. Let’s allow oth­er com­put­ers on your net­work to access it.

Set­ting this up the Right Way involves things beyond the scope of this guide. Fol­low­ing is an easy, albeit inel­e­gant, way to make your new Koha instal­la­tion acces­si­ble to oth­er machines with­in your net­work for test­ing and eval­u­a­tion pur­pos­es.

Don’t use this mod­el for a live, pro­duc­tion sys­tem. For more thoughts on mak­ing Koha avail­able to the gen­er­al pub­lic see the next sec­tion, Going Live.

Open a ter­mi­nal and do this:

sudo gedit /etc/koha/koha-httpd.conf

This is the con­fig­u­ra­tion file for the Koha web­site. You should find two Vir­tu­al­Host sec­tions. The first one is for the OPAC:


and the sec­ond one is for the admin­is­tra­tive inter­face:

## Intranet

These define your Koha web­sites. The “” means the sites will only respond when some­one requests them as “”, in oth­er words, when the web serv­er receives an incom­ing request for the web­site at address

Here’s the prob­lem with that: an IP address begin­ning with 127 always refers to the local machine. If some­one on a dif­fer­ent machine tried to access your Koha serv­er by enter­ing in their browser’s address bar, their brows­er would try to vis­it a web­site on their own machine, not yours.

Some­one access­ing our new Koha serv­er will need to do it in anoth­er way, for exam­ple by enter­ing the Koha machine’s IP address.

We need to set up the Koha Apache con­fig­u­ra­tion file so that it will accept incom­ing requests direct­ed at the Koha server’s IP address. One way to do this is to tell the Koha web­sites they should accept requests on port 80 regard­less of how they got there, i.e., regard­less of what name or IP address the brows­er used.

First you need to find the local address of your Koha serv­er. Exit from ged­it and then at the ter­mi­nal prompt enter:


The out­put will include infor­ma­tion on a few net­work adapters (cards): “eth0” is for a wired net­work card if you have one, “wlan0” for a wire­less LAN card, and “lo” is for your localhost/loopback adapter. Either the eth0 card or the wlan0 card should have your machine’s local net­work address; it might look some­thing like “inet addr:”. Remem­ber that IP address and edit Koha’s Apache con­fig­u­ra­tion file:

sudo gedit /etc/koha/koha-httpd.conf

Edit both the OPAC and Intranet Vir­tu­al­Host entries. For each entry find the “” and imme­di­ate after it enter a space fol­lowed by a par­al­lel entry for your local IP address. For exam­ple:

## Intranet

This tells Apache it should accept request not only if the user orig­i­nal­ly enters, but also if the user enters (if that hap­pens to be your Koha server’s local IP address).

Restart Apache to make the new con­fig­u­ra­tion active:

sudo /etc/init.d/apache2 restart

You should now be able to access Koha from oth­er machines on your intranet. So again, assum­ing your Koha server’s address is (which is almost cer­tain­ly isn’t) the sites’ address­es would be:

  1. OPAC:
  2. Admin:

And impor­tant­ly, you should still be able to access those sites from the Koha serv­er itself, whether you use the address­es above or the address­es we’ve used before.

  1. OPAC:
  2. Admin:

Next Section…

Part 6: Going Live

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