Koha on FreeBSD

== 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
# Remove Koha Install Directories and Configuration Files
Don't forget about any crontab entries!
Category:Documentation
Category:Installation