Koha on FreeBSD
From Koha Wiki
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
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
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.
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
$ 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):
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
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)
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::
If you're using PurePerl or Expat, you'll need to edit your ini file, typically located at:
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
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!
$ 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
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)
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
$ 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
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
$ 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 -u<kohauser> -p<kohapassword> > drop database koha;
$ 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!