Installing Koha on Mac OS X

This guide explains the installation process using Koha version 2.2.7 and Mac OS version 10.4.8 (not OS X server). Though not testet it should be pretty much the same with different versions of OS X. You are required to have some basic understanding of the unix-like darwin core which lies under the surface of OS X.

Notes in italics pertain to differences installing Koha 2.2.9 on an Intel-Mac (10.4.10 plus latest fixes, XCode 2.2.1). (submitted by Tobias V)

For Koha to work you will need a webserver, a perl interpreter and some specific modules, a mysql server and everything properly configured.

Mac OS X comes with the apache webserver v 1.3.x, this is sufficient for Koha to work, but later we'll have to adjust the configuration a little bit.

Installing mysql server is really simple. Download the Package from http://dev.mysql.com/downloads/mysql/5.0.html#downloads. Scroll down to “Mac OS X (package format) downloads” and choose the “Max” package for you CPU (up to G4 32Bit, G5 64Bit, intel x86) and OS.

When you've downloaded the diskimage, open it by doubleclicking and install the server by doubleclicking on the “mysql-max-….pkg”. Please read the notes, the installer gives to you, since they contain the information you need when encountering an error!

If you want your mysql server to start automatically at boot time you adittionally can install MySQLStartupItem.pkg. I really like the MySQL.prefPane. It adds a little control pane to your system preferences, then you can start and stop the mysql server there.

After having installed the mysql server you should run it either by running “sudo /usr/local/mysql/bin/safe_mysqld &” or using the preferences pane.

Now open a terminal window and add the mysql binaries to you search path by typing: “export PATH=/usr/local/mysql/bin:$PATH” Now you can test you installation by typing (on the terminal) “mysql -u root”. You should get a welcome message and a prompt

mysql>

If everything worked fine, then you are now connected to your server as user root. Mysql by default installs two root-users with empty passwords and two anonymous users. First you should change your administrator-password for the mysql server. You will need to provide this password to the Koha-installer later. Type:

mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd') WHERE User = 'root';

Replace newpwd with your desired password. Then delete the anonymous accounts, unless you want to keep them for some strange reasons:

mysql> DELETE FROM mysql.user WHERE User = '';
mysql> FLUSH PRIVILEGES;

Now you can quit the mysql-console

mysql> quit;

If you want to log in again you have to use the command mysql -u root -p and then provide your password. OK, your mysql installation is finished.

Perl 5.8 is preinstalled on OS X, but to have better module support and some additional tools I strongly encourage you to install the developer tools from Apple. It's free, but you'll have to create a basic account in apples developer-zone http://developer.apple.com/ and then download and install the Xcode package. It's huge (around 1GB), so be patient.

Then you'll have to install the needed Perl modules. Note: Many of these modules will be superseeded by Koha 3.0

The modules you'll need (for 2.2.7) are:

• DBI Date::Manip
• DBD::mysql
• HTML::Template
• Digest::MD5
• Mail::Sendmail
• MARC::Record
• MARC::Charset
• MARC::File::XML
• LWP::Simple
• XML::Simple
• Date::Calc
• ZOOM

This modules are optional (mainly used for barcode generation)

• PDF::API2
• GD::Barcorde
• Data::Random
• PDF::Reuse::Barcode
• Net::LDAP
• Text::Wrap

For earlier versions of Koha you'll need a few different modules, the most relevant change is Net::Z3950 instead of ZOOM(Net::Z3950 requires the YAZ-toolkit you had to compile it from the sources and there are some errors in the tests of the module, you would had to skip them).

Koha 2.2.9/OS 10.4.10/XCode 2.2.1: As build environment for yaz (and the perl-modules) I used xcode 2.2.1 from developer.apple.com as told. The source of yaz had ver. 3.0.8 and built smoothly (as did the corresponding perl-module).

Most modules install quite easy with CPAN, but please read on before doing so as not all modules do.

To install a module type in the terminal:

perl -MCPAN -e 'install "modulename"'

If you run this routine for the first time, the CPAN module will ask you a few questions about your connection and which server to use. If you get troubles with the priveliges try:

sudo perl -MCPAN -e 'install "modulename"'

There are some modules which won't install easy on Mac OS. The installation process has mainly fife parts: download, configuring, compiling, testing, installation. All these parts are executed automatically by the install command. If you see that everything runs fine up to the tests and only a few or maybe just one test fails, this does not necessary mean that the module is broken. You then can install the module with the CPAN-shell:

perl -MCPAN -e shell
cpan> make modulename
cpan> force install modulename
cpan> q

In the case of DBD::mysql I found some more work to do. Get the code with:

perl -MCPAN -e shell
cpan> get DBD::mysql

then open a subshell at the location of the files:

cpan> look DBD::mysql

In this directory patch Makefile.PL. Use your favourite text editor to find the line “$cflags .= ” -g ”;” and change it to “$cflags .= ” -Dulong='unsigned long' -g ”;” With this you tell the compiler that the word ulong means the datatype unsigned long, the OS X compiler doesn't know ulong by default.

exit the subshell with

^D

back in the cpan-shell type

cpan> install DBD::mysql
cpan> q

It still gives some warnings, but this is not a problem.

Koha 2.2.9/OS 10.4.10/XCode 2.2.1: build procedure of the Perl module DBD::mysql - in this case the documentation on the wiki is misleading as it says that after the small change of “$cflags” in Makefile.PL everything should work if you use the argument ”-force install” with cpan. ”-force install” works for almost everything but not for DBD::mysql…

The real problem (http://jayallen.org/journey/2006/04/dbd-mysql-build-problems-on-mac-book-pro) is that “mysql_config” delivers the wrong paths for cflags and libs - this is confirmed for mysql 4 and 5. (a second problem lies in the environment variables in general as osx only defines a minimal set).

Imho the best solution is to write the paths directly in the build-script but running the following lines also works:

sudo perl Makefile.PL \
–cflags=”-I/usr/local/mysql/include -Os -arch i386 -fno-common” \
–libs=”-L/usr/local/mysql/lib -lmysqlclient -lz -lm”

As cpan has no uninstall-option I recommend the switch to “cpan plus”that has the possibility to uninstall and integrates better in terminal than actual cpan…

Some remark to the actual installation process - after getting DBD::mysql working, the module-check in the installer script still doesn't recognise the module as installed. It helped to comment the module DBD::mysql out - it sounds dangerous/silly but everything runs smoothly.

Now you are ready to download and install Koha. Download the archive and extract it anywhere you want.

Since we installed MySQL 5 and Koha is not officially compatible with it, we have to patch a few files. First edit “koha.mysql”. Find the line ” return char(4) default NULL, ” and replace it by ” `return` char(4) default NULL, ” (i.e. enclose return in backticks).

Then there is a bug in the file scripts/updater/updatedatabase in line 1685 it should be ” $action = “change”; ”, not ” $action = “change $field”; ”

Koha 2.2.9/OS 10.4.10/XCode 2.2.1: The error mentioned on the wiki for “koha.mysql” is fixed in 2.2.9. The correction in …/scripts/updater/updatedatabase has still to be made.

Now navigate to that location in the terminal (did you know: you can just type “cd” and the drag and drop the folder in the terminal, its full path will be inserted.)

Start the installer by typing

perl installer.pl

The installation process is more or less self explaining, I'll give only a few hints here:

• When asked for a username and password for the Koha-database, don't provide root and you mysql root-password. This is just for Koha, you'll be asked later during the installation for your mysql root password with “To create the koha database, please enter your mysql server's root user password:”
• When asked for the intranet directory, the opac directory and the logfile directory, you could use the suggestions, but I recommend to use the location where also the “normal” websites are: /Library/WebServer (case sensitive!), so it would be
  • /Library/WebServer/koha/intranet
  • /Library/WebServer/koha/opac
  • /Library/WebServer/koha/log
  • Don't let the installer restart Apache, we'll have to make some changes first

OK, when you thru with the installer, you'll notice that the directories you specified have been populated, that's Koha.

Now to the last step: configuring apache.

First you have to edit apache's main configuration file /etc/httpd/httpd.conf

Make shure that the lines “LoadModule env_module libexec/httpd/mod_env.so”, “LoadModule mod_include libexec/httpd/mod_include.so”, “AddModule mod_env.c” and “AddModule mod_include.c” are not commented out (don't have a leading #), normaly this is true for mod_include but not for mod_env.

Koha has generated a separate configuration file for apache, it is /etc/koha-httpd.conf by default. On OS X all sub-configurations should be in /etc/httpd/users. You can safely move koha-httpd.conf there or if you don't want symlink it to there.

Now edit koha-httpd.conf to reflect your special needs. Basically you create two virtual hosts (portbased or namebased as you like). At the bottom of the configuration file is a little explanation what to do for the different versions.

If using portbased vhosts you'll need at least one more “Listen” directive for the ports you want to be reachable.

If using namebased vhosts, remember that you'll need a name resolution for that hostnames. For testing porpouses it may be enough that at least your machine knows itself. You do this by adding a entry in Apples NetInfo manager (in Applications/Utilities/NetInfo Manager)

1. Open NetInfo Manager and browse to /machines/localhost.
2. Click on the lock, you'll be promptet to provide you administrator password in order to make changes.
3. Duplicate “localhost” (Edit:Duplicate)
4. Select “localhost copy” and then select the name property in the lower window
5. Change the value of “name” from localhost to whatever the name of your virtual host is.
6. Click on one of the other directories in the list, and you will be asked if you want to save your changes. Save them.

Now finally you can start/restart apache either with the preference pane (sharing:websharing controls apache) or from the commandline. I prefer the commandline, because so you'll catch any errors.

apachectl start

or

apachectl restart

.

OK, that's it now you can use your browser and enjoy your Koha installation.