Koha on FreeBSD

From Koha Wiki
Jump to navigation Jump to search

Prolegomena

The following installation instructions have been tested only on FreeBSD 8.0. Having successfully installed Koha on FreeBSD, my recommendation would be to try and find a Debian server to use. However, if that is not possible, these instructions should give you something to work with. These instructions are based on the instructions for installing Koha on Debian.

What works: OPAC and intranet interfaces

What doesn't work:

  • patron cards
  • printing barcodes
  • non-Roman character sets

Installation Guide

All commands are performed as a system user with sudo privileges, it is not advisable by running the commands directly as root.


Prepare System and Install Dependencies

Install FreeBSD

See http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install.html

Download the disc1 ISO for your platform, burn it onto a CD, and follow the directions in the document above. I recommend installing the ports distribution and the two required distributions and nothing else. You can (and will) install everything else from ports, and this way you will avoid any dependency conflicts.

Get Koha

This installation process has been tested only with the Koha 3.2 beta, installed from git, but I would imagine that it would work with the latest stable version, as well.

For installing from git, see http://wiki.koha-community.org/wiki/Version_Control_Using_Git#Koha_Revision_Control_for_the_public

For the latest stable version (3.0), go to http://koha-community.org/download-koha/


Install additional FreeBSD dependencies

IMPORTANT: You should only use CPAN for Perl dependencies which are NOT available in ports. You have been warned!

These instructions depend on your using portsnap and portmaster. If you do not use either of these packages, you will need to modify the instructions accordingly.

Update your ports tree to the most recent: 

   $ sudo portsnap fetch
   $ sudo portsnap extract

Install Perl 5.10 (DON'T DO ANYTHING BEFORE THIS): 

   $ cd /usr/ports/lang/perl5.10 && sudo make install clean

Install portmaster: 

   $ cd /usr/ports/ports-mgmt/portmaster && sudo make install clean

Install required utilities: 

   $ portmaster gmake

Install required server software: 

   $ portmaster zebra-server apache22 mysql51-server

Install required Perl dependencies: 

   $ portmaster GraphicsMagick13 p5-Text-CSV p5-XML-LibXSLT p5-Storable p5-PDF-API2 p5-Text-CSV_XS p5-Schedule-At p5-MIME-Lite p5-GD p5-List-MoreUtils p5-DBI p5-Net-Z3950-ZOOM p5-Date-Calc p5-Mail-Sendmail p5-DBD-mysql p5-XML-LibXML p5-POE p5-Email-Date p5-HTML-Scrubber p5-XML-Dumper p5-Unicode-Normalize p5-Locale-PO p5-LWP-Simple p5-DBD-SQLite2 p5-SMS-Send p5-Test-Harness p5-Class-Accessor p5-MIME-Base64 p5-DateTime p5-MARC-Charset p5-Text-CSV p5-PDF-Table p5-Class-Factory-Util p5-Lingua-Stem-Snowball p5-Digest-SHA p5-Date-ICal p5-Getopt-Long p5-Term-ANSIColor p5-Data-Dumper p5-Lingua-Stem p5-IPC-Cmd p5-Text-Iconv p5-File-Temp p5-Date-Manip p5-XML-RSS p5-XML-Simple p5-CGI-Session p5-Digest-MD5 p5-Data-ICal p5-MARC-Record p5-Locale-Currency-Format p5-Number-Format p5-YAML-Syck p5-Time-HiRes p5-XML-SAX-Writer p5-JSON p5-YAML p5-UNIVERSAL-require p5-Net-Server p5-URI p5-Text-Tables+Wrap p5-Test-Simple p5-PDF-API2 p5-CGI-Simple p5-DateTime p5-perl-ldap p5-libwww p5-MARC-XML p5-Locale-Currency-Format p5-Memoize p5-GD-Barcode p5-Module-Install p5-ExtUtils-MakeMaker


Install Perl dependencies that aren't available through the ports system

Installing Barcode::Code128 might fail, but we don't really care, since the barcode module doesn't work under FreeBSD anyway. 

   $ cpan -fi Barcode::Code128
   $ cpan PDF::Reuse Text::CSV::Encoded Algorithm::CheckDigits Authen::CAS::Client Biblio::EndnoteStyle HTML::Template::Pro HTTP::OAI Memoize::Memcached CGI::Session::Serialize::yaml MARC::Crosswalk::DublinCore PDF::Reuse::Barcode PDF::API2::Simple


Configure the Apache server

   $ sudo ee /usr/local/etc/apache2/httpd.conf

Underneath the line that says "# Language settings", uncomment the line (i.e. remove the hash sign from the beginning): 

   Include etc/apache22/extra/httpd-languages.conf

Find the line that says "Listen 80", and add the line "Listen 8080" beneath it: 

   Listen 80
   Listen 8080

Save the file and restart Apache: 

   $ sudo apachectl restart

Configure MySQL

Copy the example my.cnf into your /usr/local/etc/mysql folder: 

   $ sudo mkdir /usr/local/etc/mysql
   $ sudo cp /usr/local/share/mysql/my-medium.cnf /usr/local/etc/mysql/my.cnf

Open the my.cnf file and add in [mysqld] and [client] the following lines: 

   $ sudo ee /usr/local/etc/mysql/my.cnf

   # UTF-8 Defaults for Koha
   [mysqld]
   default-character-set=utf8
   default-collation=utf8_general_ci
   character-set-server=utf8
   collation-server=utf8_general_ci
   init-connect='SET NAMES utf8'

   [client]
   default-character-set=utf8

   $ sudo /usr/local/etc/rc.d/mysql-server restart

Configuration of dependencies

Add koha mysql database user

The kohadatabaseuser's name will be the login user name on the intranet / staff client user interface of koha. 

   $ sudo adduser <kohadatabaseuser>
Update root MySQL password
   $ sudo mysqladmin password <password>
Create the Koha database
   Create the database and user with associated privileges:
   $ mysqladmin -uroot -pmysqlroot create kohadatabaseuser
   $ mysql -uroot -p
   
   mysql>create database <kohadatabasename>;
   mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<mysql-password-for-kohadatabaseuser>'
   Query OK, 0 rows affected (0.00 sec)

   Note: For security reasons you might chose in mysql a different password for the kohadatabaseuser. Different from its linux login password  

   mysql> flush privileges;
   Query OK, 0 rows affected (0.00 sec)

   mysql> quit

Test your SAX Parser and correct where necessary

You must be sure you're using the XML::LibXML SAX parser, not Expat or PurePerl, both of which have outstanding bugs with pre-composed characters. You can test your SAX parser by running: 

   $ cd koha-3.00.06
   $ misc/sax_parser_print.pl

You should see something like:: 

   XML::LibXML::SAX::Parser=HASH(0x81fe220)

If you're using PurePerl or Expat, you'll need to edit your ini file, typically located at: 

   /usr/local/lib/perl5/site_perl/5.10.1/XML/SAX/ParserDetails.ini

move these lines to the bottom of the file: 

   [XML::LibXML::SAX::Parser]
   http://xml.org/sax/features/namespaces = 1

Run the Koha installer

   $ perl Makefile.PL

You will need to answer the questions. Please note that the later instructions here rely on the assumption that you have chosen to do a "dev" install. If you want to do a different type of installation, you can use `sudo gmake install` instead of `gmake install` but you will need to alter the directions that follow to greater or lesser degrees. 

   $ gmake
   $ gmake test
   $ gmake install

Steps after the installation

Environment variables

In order to use Koha's command-line batch jobs, you should set the following environment variables: 

   export KOHA_CONF=/home/<kohauser>/kohaclone/koha-conf.xml
   export PERL5LIB=/home/<kohauser>/kohaclone

Configure and start Apache

   $ sudo ln -s /home/<kohauser>/etc/koha/koha-httpd.conf /usr/local/etc/apache2/Includes/koha-httpd.conf

Note that the path to koha-httpd.conf may be different depending on your installation choices. 

   $ sudo apachectl restart

Note: you may still see the usual Apache default site if your VirtualHost configuration isn't correct.

Configure and start Zebra

Note: Other ways of configuring Zebra are discussed in the Koha documentation. However, this is the only way that has actually been tested on FreeBSD.

Copy the koha_zebra rc.d script to from kohaclone/freebsd to /usr/local/etc/rc.d/ 

   $ sudo cp freebsd/koha_zebra /usr/local/etc/rc.d/

Enable the koha_zebra service in rc.conf 

   $ sudo ee /etc/rc.conf
   > koha_zebra_enable="YES"
   > koha_zebra_user="<kohauser>"

Note: that second variable (koha_zebra_user) is very important!

Start zebra: 

   $ sudo /usr/local/etc/rc.d/koha_zebra start

Run the Web Installer, populate the database, initial configuration of settings

Point your browser to http://<servername>:8080/

It should redirect you to the Web Installer where you can continue the setup. You can install the sample data for libraries, patrons, etc. via the Web Installer

What next?

Once the installer has completed, you can import and index MARC records from the command line thusly (Note: you can also use the 'Stage MARC records for import' from the Tools area of Koha's Staff Client to import a batch of MARC records): 

   $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml

(note: use the correct path to your koha-conf.xml)

Import data

Bibliographic data in MARC21 format 

   $ misc/migration-tools/bulkmarcimport.pl -file /path/to/marc.iso2709

Authority data in MARC21 format 

   $ misc/migration-tools/bulkauthimport.pl -file /path/to/auth.iso2709

Fast Index

   $ misc/migration-tools/rebuild_zebra.pl -b -w

Once the indexing has completed, you will be able to search for records in your system. NOTE: if you don't run the Fast Index utility, and you have the index updates scheduled as per 7.3 the indexing process will happen in the background, but it will be orders of magnitude slower.

Schedule regular index updates

Run rebuild_zebra.pl -b -a -z as a regular cron job, check misc/cronjobs/crontab.example for usage examples

Upgrade

If you are upgrading from a previous installation of Koha 3, you can use the following: 

   perl Makefile.PL --prev-install-log /path/to/koha-install-log
   gmake
   gmake test
   gmake upgrade

Uninstall Instructions

Stop Services

  $ sudo rm /usr/local/etc/apache2/Includes/koha-httpd.conf
  $ sudo apachectl restart

  $ sudo /usr/local/etc/rc.d/koha_zebra stop
  $ sudo rm /usr/local/etc/rc.d/koha_zebra

Remove Database and Indexes

MySQL

  $ mysql -u<kohauser> -p<kohapassword>
  > drop database koha;

Zebra Indexes

  $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
  $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
  1. Remove Koha Install Directories and Configuration Files

Don't forget about any crontab entries!

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_on_FreeBSD&oldid=918"