Disclaimer

THIS ARTICLE IS VERY OUTDATED

Perhaps see Koha_on_a_Raspberry_Pi_2 instead.

Some of the things described here work more easily nowadays than they did when I wrote this. In general, use the latest Raspian version, it should work now. The Raspberry Pi Model B/B+ comes with 512mb of RAM now, you can turn the GPU share of the RAM down to 16mb and you can overclock the CPU. You can also do all the resizing-partitions things from within Raspian. You will find more information about these things on the Raspberry Pi website and forum.

Also Plack is getting more stable these days, but there are still areas that will just not work using Plack.

Raspberry Pi?

Raspberry Pi is a tiny ARM-based computer. The Raspberry Pi foundation is a UK based charity with the intention of providing an affordable learning plattform to school children to get into using computers and programming. A version with an ARM11 700Mhz CPU and 256MB RAM is available for $35 US. Its performance is comparable to a Pentium II 300mhz, but with a powerful GPU. It is powered by USB/5V.

The device is not free/ open hardware :(

More info at http://www.raspberrypi.org/

Warning: this is only a proof of concept. It works, but it is slow.

You need…

1 Raspberry Pi
1 Power supply
1 SD card or MicroSD card with SD adapter, 4GB+
a computer to work on

You will need at least a 4GB SD card for this to work! There is certainly stuff in the Debian image that you can remove for our purpose (like LXDE), but I did not look much into this. Removing LXDE and dependencies will not give you enough disk space for all dependencies you need for Koha to run.

Install Debian

Create and resize your SD card

I used the Debian image for Raspberry Pi from http://www.raspberrypi.org/downloads (Version debian6-19-04-2012.zip). This image contains a lot more things than you need to run koha (like a Desktop Environment), but it makes the Debian "installation" pretty easy. There is a guide to put the image on the SD card and how to resize partitions to use the full diskspace of the SD card. I moved the 200mb swap partition at the end of the disk and resized the Linux partition to use all free space. Create and resize now!

Enable SSH and more RAM

Unfortunately the Raspberry Pi is not free/ open hardware and the FAT32 partition includes non-free stuff needed to boot. After creating and resizing the partitions, mount and open the FAT32 partition on the SD card and

rename boot_enable_ssh.rc to boot.rc to enable SSH
copy arm224_start.elf to start.elf to change shared memory to 224/32MB (RAM/GPU)

There is no option to disable the GPU and use all 256MB of RAM since the GPU is needed to boot. Note that swap is disabled by default because it is said to be very slow. If the 224MB of RAM are not enough for you, consider using a usb stick as swap partition. I did not need swap for the Koha installation but for other experiments.

After the changes on the FAT32 partition, unmount all mounted SD card partitions.

Put the SD card into your RasPi and turn on power. Wait a minute and connect via SSH. Username is pi, password is raspberry. I use an OpenWRT router with DHCP enabled in my network, so I opened the OpenWRT interface and found the IP of my Raspberry PI. In a different setup you may want to do network settings on the SD card before (if that is possible).

SSH to the RasPi

We use SSH to connect to the RasPi. One advantage of this method is that we do not need an extra monitor.

 mirko@rechner:~/$ ssh pi@192.168.1.238
 pi@192.168.1.238's password:
 Linux raspberrypi 3.1.9+ #90 Wed Apr 18 18:23:05 BST 2012 armv6l
 
 The programs included with the Debian GNU/Linux system are free software;
 the exact distribution terms for each program are described in the
 individual files in /usr/share/doc/*/copyright.
 
 Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
 permitted by applicable law.
 /usr/bin/xauth:  creating new authority file /home/pi/.Xauthority
 pi@raspberrypi:~$

Change/ set passwords

Before you do anything else, change the default password!

 pi@raspberrypi:~$ passwd
 Changing password for pi.
 (current) UNIX password: 
 Enter new UNIX password: 
 Retype new UNIX password: 
 passwd: password updated successfully

Set a root password!

 pi@raspberrypi:~$ sudo passwd root
 Enter new UNIX password: 
 Retype new UNIX password: 
 passwd: password updated successfully

You can switch to root for convenience since we will install a few things, you don't need to type sudo all the time

 pi@raspberrypi:~$ su
 Password: 
 root@raspberrypi:/home/pi#

There was a user 'Suse' in my version of the Debian image. I deleted the line corresponding to that user in the sudoers file

 root@raspberrypi:/home/pi# visudo

You may also wish to reconfigure your time zone.

 root@raspberrypi:/home/pi# dpkg-reconfigure tzdata

Add the Koha repository

I had problems with koha-create in Koha 3.8 from the official repository. As a workaround I used Jared's repository, installed 3.6 and upgraded from the koha-community repository to 3.8 afterwards. There is now also 3.6 in the official repository. It is called 'oldstable'. It is the default repository if you copy the settings below.

Note that there are no packages for ARM architecture in the repositories yet. The packages do work however since they include no architecture specific binaries. We have to point apt directly to the folder, otherwise it will complain that there are no ARM packages. That is why the URLs look slightly different than you are probably used to.

Open /etc/apt/sources.list with the editor of your choice, eg.

 root@raspberrypi:/home/pi# nano /etc/apt/sources.list

Add the following lines at the end of the file. If you leave the comments like this, you will get Koha 3.6.

 # koha 3.6
 deb http://debian.koha-community.org/koha dists/oldstable/main/binary-i386/
 
 # koha 3.8
 #deb http://debian.koha-community.org/koha dists/squeeze/main/binary-i386/

Save the file and exit the editor. Add the key for the Koha repository.

 wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

Then update your packages

 root@raspberrypi:/home/pi# apt-get update
 root@raspberrypi:/home/pi# apt-get upgrade

This may take a while.

Install Koha

 root@raspberrypi:/home/pi# apt-get install koha-common

That will show a lot of dependencies and needs about 600MB. This is the point where a 2GB SD card is not enough. I told you so.

 0 upgraded, 196 newly installed, 0 to remove and 0 not upgraded.
 Need to get 122 MB of archives.
 After this operation, 601 MB of additional disk space will be used.
 Do you want to continue [Y/n]?

I still got the following message, despite having imported the key

 WARNING: The following packages cannot be authenticated!
   libcgi-session-driver-memcached-perl libgravatar-url-perl koha-common
 Install these packages without verification [y/N]?

This may have to do with the bending of the repository address. I said yes here. You may not want to do that if you cannot verify that it is what you want.

At some point I got the error

 Failed to fetch http://ftp.uk.debian.org/debian/pool/main/libe/libemail-date-perl/libemail-date-perl_1.103-2_all.deb  Hash Sum mismatch

I did apt-get update again and then it worked.

There was also a problem with the Apache setup

 Starting web server: apache2apache2: bad group name www-data
 Action 'start' failed.
 The Apache error log may have more information.
  failed!
 invoke-rc.d: initscript apache2, action "start" failed.

the user www-data is created at installation but the group is not. Do it manually and restart apache

 root@raspberrypi:/home/pi# addgroup www-data
 root@raspberrypi:/home/pi# usermod -a -G www-data www-data
 root@raspberrypi:/home/pi# /etc/init.d/apache2 restart

At this point you should be able to see the "It works!" Apache page when navigating the browser on your non-Pi computer to the IP address of the Pi.

Now disable the default Apache site, install mysql-server and create a Koha instance

 root@raspberrypi:/home/pi# a2dissite default
 Site default disabled.
 Run '/etc/init.d/apache2 reload' to activate new configuration!

Install mysql-server

 root@raspberrypi:/home/pi# apt-get install mysql-server

Create a Koha instance (name here is 'koha', use what you like)

 pi@raspberrypi:/home/pi# sudo koha-create --create-db koha

Reload the Apache config

 pi@raspberrypi:/home/pi# sudo /etc/init.d/apache2 reload

You will find your password in the koha-conf.xml file. Log in to http://<your-ip>:8080/ and run the web installer. That's it.

Performance

A regular Koha 3.8 is functional, but very slow on the Raspberry Pi. Loading times for OPAC interface or search results were between 20 and 30 seconds on the test installation, sometimes even slower.

However there have been new developments regarding Koha performance lately, one very important step forwarding being the use of Plack. This enhancement is so far only usable in the development version of Koha. It is not intended for use in production yet.

Plack works by caching a lot of things in RAM. Since RAM is very limited on the RasPi we might run into problems here. On a test installation with 1000 biblios and the latest Koha Master it works and gives a huge performance boost compared to the 3.8 installation without Plack. You have to expect search times >10s but things may speed up for pages that you have loaded before, the staff client seems to benefit a lot from this.

Need more RAM!?

Apache: stop Apache running the non-plack Koha
MySQL: put DB on a different Server (eg. 2nd Pi)?
MySQL: use SQlite instead?
GPU: use less than 32MB if only needed to boot?
Any software running that we don't need?
[…]

Update

I have put some more information about performance including OPAC screen recordings here.

Staff client benchmarks can be found here.

Koha on a Raspberry Pi

Contents