The Emilda 1.1 Administrators Guide is the Emilda manual for site administrators who wish to install and maintain an Emilda 1.1.x environment.
Emilda was built to work with the requirements above. There is however no good reason why it should not work on another platform with other backend applications, although this might require some changes to the Emilda source. Alternative set-ups have not been tested, but if You do succeed to set up Emilda on an other system, please let us know what Your system looks like and a few steps to reproduce.
Following these installation directives will give You a working Emilda environment on at least a Mandrake 9.1 machine, on which this file was written. These directives should, however, give ideas of what is compulsory for a successfull environment and as such give You an idea what to do also on other platforms.
- INSTALL A BASE SYSTEM. Mandrake 9.1 comes with Apache 2 and MySQL 4.0. If using an other platform, install Apache 1 or 2, favourably 2, but skip MySQL for now.
- INSTALL YAZ. (http://www.indexdata.dk/yaz/) Emilda 1.0 has only been tested using Yaz => 2.0.2, but should at least work with other Yaz 2.x-versions. Feel free to use Yaz 1.x-vesions at own risk. Build fron source if the favourable type to install, but if Your architecture has precompiled versions feel free to use these.
- INSTALL ZEBRA. (http://www.indexdata.dk/zebra/) Emilda 1.0 has only been tested using Zebra => 1.3.10, but should work using also other versions (except 1.3.14, see note below). Zebra should, stressing the word "should", be built from source. Special attributes to use when compiling Zebra is '--with-perl' since the Perl-API of Zebra is required by Emilda to manage Zebra from within the system. After making Zebra, go to the perl/ subfolder in the Zebra src-folder and install the perl library located there. Before making the source there, make sure that you edit the Makefile and search for "MakeMaker const_loadlibs section". A few lines under that string you should add in EXTRALIBS and LDLOADLIBS the -lexpat parameter before the -lxml2 parameter. Should look something like this: ... -L/usr/lib -lexpat -lxml2 ...
IMPORTANT NOTE!!
During QA it was noticed that version 1.3.14 of Zebra contains a bug that will break Emilda MARC management functions and should NOT be used with Emilda under any circumstances. In versions of Zebra prior to 1.3.14 the problem doesn't exist, and in version 1.3.15 this issue has been corrected. As such we encourage Emilda users to upgrade to version 1.3.15 or later of the Zebra server.- INSTALL SABLOTRON. (http://www.gingerall.com/charlie/ga/xml/p_sab.xml) Sablotron in itself has dependencies, which need to be satisfied, but of these only Expat (http://www.libexpat.org/) is required. The JavaScript extension is optional, since it is not required by Emilda 1.0.
- INSTALL MYSQL. (http://www.mysql.com) !! Emilda 1.0 requires MySQL => 4.1 !! If installing precompiled packages (e.g. rpm), be sure to install development & header files, so that PHP might include the appropriate header files.
- INSTALL GD The Emilda default layout generates its submenu inages with GD, and as such GD is needed in PHP. Each platform should have GD as a bundled package, but if You for some strange reason cannot find it, try building it from source.
- INSTALL PHP. (http://www.php.net) Emilda 1.0 has only been tested using PHP => 4.3.1 and is most certainly only going to work on 4.x-versions of PHP. As it, however many times has been proven, nothing is impossible; if You are of masochistic nature and find tweaking Your favourite waste of time, You might get it working using older versions of PHP. Additional to the configure parameters You choose to use, be sure to have the following:
--with-mysql
--enable-xslt
--with-xslt-sablot
--with-zlib
--with-yaz
--with-gdIf You choose to omit --with-apxs or Your architecture does not support apxs, be sure to configure Your Apache to utilize PHP.
These packages kan either be installed using the CPAN-shell in perl (perl -MCPAN -e shell) or by downloading separate source-files and compiling them individually. Dependencies of the following libraries are only valid on a "clean" Mandrake 9.1 install, and may vary greatly from case to case.
- Net::Z3950 (http://search.cpan.org/author/MIRK/Net-Z3950-0.35/)
Prerequisites:
- Event (http://search.cpan.org/author/JPRIT/Event-0.87/)
- MARC::Record (http://search.cpan.org/author/PETDANCE/MARC-Record-1.29/)
HTML::HTMLDoc (http://search.cpan.org/author/MFRANKL/HTML-HTMLDoc-0.06/)
Prerequisites:
- HTMLDOC (http://www.easysw.com/htmldoc) This is a program, not a perl library as it will become clear. This is a prerequisity to the perl htmldoc-API HTML::HTMLDoc, which is required by Emilda 1.0.
- GD::Barcode (http://search.cpan.org/author/KWITKNR/GD-Barcode-1.14/)
- DBD::MySQL (http://search.cpan.org/~rudy/DBD-mysql-2.9003/lib/DBD/mysql.pm)
The following steps need to be performed in the exact order they are given here, to prevent unwanted actions. (nothing disastrous can happen) If You are not totally sure about what You are doing, consider contacting someone who does, since doing something wrong might damage data in Your database.
- LOG INTO MYSQL Log into mysql using the "mysql"-tool. You have to have root access to the MySQL database.
COMMAND:
mysql --user=root --password='rootpass'
- CREATE DATABASE The next thing to do is create the Emilda database.
COMMAND:
create database emilda;
The name of the database can be anything, but if You change it from 'emilda' remember to change it in the configuration.
- GRANT PRIVILEGES After creating the database we want to grant privileges to the new database to some user, since we do not want Emilda to run with the root user.
COMMAND:
grant all privileges on emilda.* to emilda@localhost identified by 'password';
If You specified another database name than 'emilda' You need to alter the syntax here; change 'emilda' in 'emilda.*' to Your database name. Further, if You want another username than 'emilda' change the 'emilda' in emilda@localhost to Your alternative. Finally replace 'password' with the password You choose. Remember to update the configuration.
- EXIT MYSQL Leave the MySQL server.
COMMAND:
exit;
- CREATE TABLE-STRUCTURE What we want to do next is to fill the empty database with tables. To do this, You need to enter the sql/ directory in the Emilda root-folder. After this proceed followingly:
COMMAND:
mysql emilda --user=emilda --password='password' < emilda.sql
where the first argument after 'mysql' is the name of the database, the second the user, the third the password of the user.
It is imperative to have all folders correctly for the system to work. To assure that You have all folders in their correct places, follow the below instructions.
COPY THE SOURCE FOLDER You will want to have the Emilda-source, src/ folder in Your document-root. (e.g. /var/www/ or /var/www/html/) If You have dedicated the server entirely to Emilda and no other projects are to be run on the computer, You can copy the files directly into the document-root, otherwise it is wise to copy them into a subfolder. (e.g. /var/www/Emilda)
- ZEBRA FOLDER You need to have a Zebra root-folder somewhere on the server. This folder contains all Zebra configuration files and specifications. The location of this folder is uninteresting, since it can be configured in the "Zebra configuration"-section. Inside the zebra root-folder You need to have a subfolder containing MARC-records. Also the name of this folder is configurable. What however is important is that both the "zebrasrv"-process and apache have write access to the records folder.
After completing all the sections above it is time for fine-tuning.
- GENERATE MARC RULES We need to generate some MARC-rules so that Emilda knows e.g. what indicators are allowed in which subfields. For this we use the MARC-rules supplied with MARC::Lint. As these rules are updated with every release of MARC::Lint we do not supply these rules, but insted a script that will copy the rules from MARC::Lint to Emilda understandable. The is done followingly:
1. Go into the perl/ folder in the source folder (cd /path/to/source/perl/)
2. Run read_Lint.pl with the argument '../MARC_defs' (./read_Lint ../MARC_defs)
- CONFIGURE APACHE Emilda requires some configuration directives to be present in Apache to work correctly. You can configure it either as a virtual host or as a directory. See in the Sample Configurations-section for an example on a virtualhost/directory configuration. Restart Apache after modifying your configuration file.
- CONFIGURE EMILDA Last but not least You need to configure Emilda to suit Your system. This You can do by running './configure' in the Emilda source folder. Go through all sections to see if there is anything that is to be changed.
One account has been created automatically for the system administrator. Use it to create users and configure Emilda further, just remember to change the password! The login information for the admin account is:
username: admin
password: test
Hope this helps you on the way to get a working Emilda environment. If you experience difficulties, you can always ask via the Mailing lists.
This is a sample Directory for Apache. Do not use directly, but alter with the help of the description below.
<Directory /var/www/emilda> AddHandler cgi-script .cgi .pl php_value include_path .:lib AllowOverride All Options ExecCGI FollowSymLinks Order allow,deny Allow from all <Files "*.inc"> Order allow,deny Deny from all </Files> </Directory>
This is a sample VirtualHost for Apache. Do not use directly, but alter with the help of the description below.
<VirtualHost *> ServerName emilda.example.com ServerAdmin webmaster@example.com DocumentRoot /var/www/emilda AddHandler cgi-script .cgi .pl php_value include_path .:lib <Files "*.inc"> Order allow,deny Deny from all </Files> <Location "/"> AllowOverride All Options ExecCGI FollowSymLinks Order allow,deny Allow from all </Location> CustomLog logs/Emilda.log combined </VirtualHost>
<VirtualHost *>
Declares the beginning of the VirtualHost. Replace * with the IP of your server if you want Apache to specify this VirtualHost to only a specific IP. (Can be useful if your server is accessible via multiple IPs)
ServerName emilda.example.com
Declares the name of the VirtualHost, i.e. the domain name that Emilda will be accessed with. This domain must exist!
ServerAdmin webmaster@example.com
The email address of the person responsible for this VirtualHost. Will be visible if server fails.
DocumentRoot /var/www/emilda
The full path to the Emilda source folder
AddHandler cgi-script .cgi .pl
Allows execution of Perl/CGI scripts outside the cgi-bin-directory
php_value include_path .:lib
Declares a PHP-value defining the location of Emilda includes
<Files "*.inc">
Order allow,deny
Deny from all
</Files>
Deny access to all .inc filed via Apache for security reasons
<Location "/">
AllowOverride All
Options ExecCGI FollowSymLinks
Order allow,deny
Allow from all
</Location>
Allow the execution of Perl/CGI scripts in the Emilda source folder and sub-folders and deny listing of files.
CustomLog logs/Emilda.log combined
Specify Apache to separate the access log of this VirtualHost from the others. The path can be which ever, but be sure that apache has write access there
</VirtualHost>
End VirtualHost declaration
Below are some directives how to configure Zebra to comply with Emilda in an acceptable manner.
The first thing to be done is to decide where the Zebra folder is to be located. If you do not have any particularly good reason why not to put this folder as a subfolder of the Emilda source folder, we recommend that you put it as a subfolder of the Emilda source folder named zebra/.
What you need to put into this folder, is the sample USMARC configuration supplied with the Zebra source. If you feel familiar with the Zebra configuration you can of course customize this process. For more information on where to locate the USMARC configuration samples, please consult the README supplied with the Zebra source.
Now we have a working environment where the "zebrasrv"-process can live and work, but this is not enough for Emilda as Emilda uses attributes that are not defined in the default configuration supplied with Zebra. That is why we have supplied a tarball containing all the files that need to be replaced in Your Zebra root folder and it can be downloaded here. Unpack the tarball in some arbitraty location, and copy the files to their appropriate locations (see below).
Before starting Zebra, we need to create a folder where the MARC-records are to be stored. In our examples it is named records/ and it is located in the Zebra root folder (/path/to/emilda/zebra/records/). What is important with this folder is that both the Zebra process and Apache need to have write access to this folder. This can be achieved e.g. by running the "zebrasrv"-process as the Apache user and only giving the Apache user write access to records/, or then give write access to records/ to both Apache and the user running the "zebrasrv"-process. There is no favourable way to do this; both work just as well.
After deciding on which method to use, we are ready to prepare zebra for running; zebra needs to init and index the records/ folder before we start the process. If you have any records that you wish to import into Emilda, you need to copy these into the records/ folder before running these commands. (If you afterwards want to import MARC-recods, you copy them into the recods/ folder and run these commands.)
This should give you a working environment where there are no anomalies regarding Zebra and Emilda interaction at least.
NOTE!
If the records/ folder is empty, there will be an error of the type
Unsupported Use attribute: 7
which should not show up after the first record has been added. If it persists, there is something odd going on; try to check if you have done everything according to the above instructions, or send a note to the Emilda mailing list.