Emilda 1.2 Administrators Guide

The manual for setting up a working and optimized Emilda 1.2.x environment either from scratch, or alternatively upgrading from an existsing setup.

Emilda Up Until Today

Even though Emilda is still oven-fresh on the OpenSource market, the foundations are conciderably aged. Emilda first took shape in autumn 2000 as the final project of a Perl course. Yes, initially Emilda was written in Perl, but this was something really basic, but it still was the foundation to the logics behind the entire project. This was also when the, by today almost legendary layout took shape; it is pretty remarkable to have a layout remaining unchanged for three years without having anyone nagging on it.

By New Year 2000 the Perl version of Emilda was completed, but that was when we realized the potential in making a Library Management system. So we gathered all our equipment and experienced the for that time most wearing development-week we had experienced. That was also when Emilda changed from being a Perl project to become written in PHP. This change in programming language has been internally debated resulting in the general consesus that Emilda may in future be rewritten into Perl.

What we however did wrong at this development session in February 2001 was that we did not investigate in library standards but instead only responded on the demands of the school that Emilda was to be shipped to after completing. This was probably the biggest mistake that was committed during the lifespan of Emilda; we narrowed the possible clients to exactly one school, which however was more than satisfied.

At this time Emilda was not developed under the GNU GPL but did also not cost anything. This was the first time that we inofficially decided that the next release of Emilda would be under the GNU GPL.

It was however, almost two years until the next release of Emilda saw the light of dawn; Emilda 1.0.0. In March 2003 a bid-round induced by SBUC for the renewal of their Library System came to our attention; we responded with a release plan of our next version of Emilda: 1.0.0 released under the GNU GPL and we got the order.

This was when Emilda as it can be seen today started to take shape. We had made thorough investigations in library standards and tehnology and started to implement these into the old, non-standard procedures of Emilda. After 10 weeks of hard development the first version of Emilda released under the GNU GPL was reality which includes amongst others:
• 100% MARC compatibility
• Template based layout
• Z39.50 searching
• XML based language management
There is when studying the Emilda at its current state not much legacy from old versions left; from the initial Perl Emilda there is absolutely nothin left, and even from the initial PHP version of Emilda, there are only the layout and session management functions left. But again, if there is no change, how can there be development?

Looking back on the old versions of Emilda gives one nostalgic memories of what development and visions were like then, but without these visions we most certainly would not have gotten this far. Seems like megalomania and software development go together like pies and carrots; prove me wrong if You can.

System Requirements

"The easy way"-requirements:

• Linux base system (e.g. Debian is highly recommended)
• Apache web server
• Mysql server (As of 1.2-alpha, Emilda also supports version 3 of MySQL.*)
• PHP, Yaz enabled
• Perl
• Zebra server
• Basic database administration skills

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 setups (such as Microsoft Windows) have been attempted, but they require hard work and both administrative and coding skills. The biggest problems you will experience when attempting a Windows install is getting the correct MySQL client version and getting the Zebra Perl module installed.


General requirements:

• A web server with support for PHP
• SQL database server
• PHP with YAZ
• Perl
• Z39.50 server, supporting favourably MARC, but other formats are also possible
• Console tells You more than just 'ls'

* The official, and supported database version of MySQL is 4.1.x. As such, we cannot debug or give support for errors related to usage of an earlier database version. As of 1.2-alpha, however, Emilda has been tested to work with both 3.23.x and 4.0.x, so even though we encourage you to upgrade your MySQL server it is not required.

Emilda Online Demo

You can access an online demo of Emilda at http://demo.emilda.org/. The databases at the demonstration site are reset every 24 hours. As such, any users, books or messages that you create exist only 24 hours max. If you have any questions concerning either the online demo or Emilda in general, please write to the Emilda mailing lists.

Fresh installation

Instructions for setting up a fresh, Emilda 1.2.x environment

Installation Process

I. MAIN APPLICATIONS

The below instructions at least gave me a working environment on my Debian/Unstable workstation, but should also serve as directives how to get Emilda working on your computer.

1. INSTALL A BASE SYSTEM. Debian/Unstable comes with MySQL 4.0, so if you find yourself satisfied with this, you can install this as a .deb package, otherwise we recommend installing a precompiled binary release from the MySQL site. Using a precompiled version will - at least to our knowledge - supply you with a more stable environment than if you compile it from source, but this is entirely individual.
2. INSTALL YAZ. (http://www.indexdata.dk/yaz/) Emilda 1.2 (and earlier) 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. At least on Debian, using Apt is a good idea, just follow the instructions on the Indexdata site how to change your /etc/sources.list to comply with Indexdata downloads.
3. INSTALL ZEBRA. (http://www.indexdata.dk/zebra/) Emilda 1.2 (and earlier) has only been tested using Zebra => 1.3.10, but should work using also other versions (except 1.3.14, see note below). We however recommend using 1.3.15+. 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 install version 1.3.15 or later of the Zebra server.

4. INSTALL MYSQL. (http://www.mysql.com) As of 1.2-alpha it is possible to use versions 3.23 and above of MySQL, but we strongly recommend using version 4.1.2+ for any version of Emilda. When installing precompiled files, remember to install development headers so that PHP can include the correct "libmysqlclient"-headers.
5. INSTALL GDThe old layout of Emilda uses GD to generate images, and as such it is a good idea to install GD support in PHP. For this, you need to install GD on your system, which on Debian works like a charm using Apt.
6. INSTALL PHP. (http://www.php.net) It is wise not to try to use Emilda 1.2.x with older PHP versions than 4.3.x as problems might arise, especially with the Object model. In addition to the configure parameters you choose to use, be sure to have the following:

   --with-mysql
   --with-zlib
   --with-yaz
   --with-gd
   --with-gettext
   --with-ldap (optional; needed for LDAP authentication)

   If you choose to omit --with-apxs or your architecture does not support apxs, be sure to configure your Apache server to utilize PHP.

II. PERL LIBRARIES

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 might already be met, so use consideration from case to case.

Use the install command in the CPAN-shell.

1. Net::Z3950 (http://search.cpan.org/author/MIRK/Net-Z3950-0.35/)

   Prerequisites:

   • Event (http://search.cpan.org/author/JPRIT/Event-0.87/)
2. MARC::Record (http://search.cpan.org/author/PETDANCE/MARC-Record-1.29/)
3. GD::Barcode (http://search.cpan.org/author/KWITKNR/GD-Barcode-1.14/)

4. DBD::mysql (http://search.cpan.org/~rudy/DBD-mysql-2.9003/lib/DBD/mysql.pm)

III. MYSQL CONFIGURATION

The following steps need to be performed in the exact order they are given here, to prevent unwanted actions. 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.

1. 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'

2. 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.

3. 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.

4. EXIT MYSQL Leave the MySQL server.

COMMAND:

exit;

IV. DIRECTORIES SETUP

It is imperative to have all folders in place for the system to work. To assure that you have all folders in their correct places, follow the below instructions.

1. 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 will 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)

2. 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 the Apache web server (typically username 'www-data' or 'apache') have write access to the records folder.

   New in Emilda 1.2 is the usage of shadow registers to allow fast and secure updates of the database. As such, depending on your database size, the zebra folder might consume considerably large space, and there is no check that there is enough space available. Please make sure that you assign the zebra folder enough space to operate.

V. SYSTEM CONFIGURATION

After completing all the sections above it is time for fine-tuning.

1. 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 customizing the .htaccess file supplied with Emilda 1.2. See in the Sample Configurations-section for an example on a virtualhost configuration. Remember to restart Apache after modifying your configuration file.

VI. CONFIGURATION

1. SETUP EMILDA Run the setup.php script supplied with Emilda to ensure that your system is sane, and properly configured. You do this by pointing your favourite browser to the Emilda "location", and accessing setup.php (e.g. http://localhost/emilda/setup.php) and following the on-screen instructions. When installing a fresh installation the emilda.sql file is needed by setup.php. You should copy the sql directory from the Emilda tarball to your Emilda www-root so that setup can use it. After a successful installation, the sql directory can be removed. It is adviceable to disallow setup.php from web users after running it.

2. SETUP LANGUAGES To get languages working correctly, upgrade your locale linkage folders in the ./locale folder. You do this by going into the Emilda source folder and executing the following command:

   sh bin/locales.sh

   In addition you need to compile the languages to support these. This is done by going into the source folder and executing the following command:

   sh bin/compile_languages.sh

3. CONFIGURE EMILDA Last but not least you need to configure Emilda to suit your system. This you do by using the Emilda configuration section, which of version 1.2-alpha is within the Emilda system. The Configuration Panel can be found under the Management icon in Emilda. To log in, use the administrator account information provided when you ran setup.php.

VII. LOGIN AND HAVE FUN!

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 was provided when setup.php was run.

Zebra Configuration

Sample Zebra Configurations

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. We recommend that you put it as a subfolder (zebra/) of the Emilda source folder. One reason not to have it there is when the Zebra database is bigger than the disk that the Emilda source folder is located on. In such cases, it might be a good idea to put it on a separate drive.

There are two ways to configure Zebra to comply with Emilda; either configuring it from the example files supplied with the Zebra source, or using the pre-configured setup supplied with Emilda.

When configuring from the examples supplied with Zebra, you need to put the USMARC example files into your zebra-root. They are normally located in test/ under the idzebra source folder. Additionally you need to put the tab/ folder from the idzebra source folder into your zebra-root. You can of course use a custom setup if you feel familiar with Zebra configuration.

Now we have a working environment where the "zebrasrv"-process can live and work, but this is not enough for Emilda as it 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 from the same location you downloaded Emilda itself, named "emilda-zebra-folder-VERSION.tar.gz". Unpack the tarball in some arbitraty location, and copy the files to their appropriate locations (see below).


• zebra.cfg - The Zebra root folder (/path/to/emilda/zebra/zebra.cfg)
• bib1.att - The tab/ subfolder of the Zebra root folder (/path/to/emilda/zebra/tab/bib1.att)
• usmarc.abs - The tab/ subfolder of the Zebra root folder (/path/to/emilda/zebra/tab/usmarc.abs)
• usmarc.tag - The tab/ subfolder of the Zebra root folder (/path/to/emilda/zebra/tab/usmarc.tag)

If you want to use our pre-configured zebra environment, download the tarball and extract into the location where you want your zebra-root to exist. This tarball contains all necessary files for Zebra to work with Emilda, so no configuration should be needed.

Before starting Zebra, we need to create a folder where the MARC-records are to be stored. In our examples it is called 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 it. 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 by giving 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.) However, remember that the Items that the records in the records/ folder represent need to be added into the SQL database before Emilda can use them.


1. Go into the Zebra root folder: "cd /path/to/emilda/zebra/
2. Init Zebra: "zebraidx init"
3. Index the records/ folder: "zebraidx -g emilda update records"
4. Commit results into shadow: "zebraidx commit"
5. Start the zebrasrv-process: "zebrasrv -l /path/to/log @:9999"

This should give you a working environment with Emilda and Zebra.

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.

Upgrading

This section explains how to upgrade an existing Emilda setup to 1.2.x. Below you'll find instructions on how to upgrade between different versions. If you upgrade from an older version, you should follow each step in the progress, i.e. upgrading from 1 -> 3 you would do 1 -> 2, 2 -> 3. Make sure you read the right sections and do the right steps to achieve a fully working Emilda environment.

from 1.2.x to 1.2.y

Emilda

Emilda 1.2.x releases are stable bug fix releases. As such, they only fixes a few minor code issues. Upgrading to 1.2.x can be done by simply overwriting the contents of the existing src folder with the contents of the new src folder (make sure you don't have anything else than source files in that folder).

The easiest way, however, is to use the supplied 1.2.x patch. Download the patch, save it in your current emilda src folder (the one with all the .php files) and issue the following command (in the src folder):

gunzip emilda-1.2.x.patch.gz
patch -p2 < emilda-1.2.x.patch

If there is an emilda-1.2.x-lang.patch.gz file available, the language files have changed too. Download this patch, save it in your emilda lang folder and issue the following command (in the lang folder):

gunzip emilda-1.2.x-lang.patch.gz
patch -p2 < emilda-1.2.x-lang.patch

After this the new language files need to be compiled as usual.

Watch out for any errors or warnings. After this run setup.php to make sure your system is up-to-date. If everything was successful, you should have a working Emilda 1.2.x environment.

Zebra

This is only required for Emilda 1.2.1.
The zebra folder has changed in 1.2.1. Turn off your zebra server. Make sure you don't loose your records folder and replace your existing zebra folder with the new one (the tab/bib1.att file has changed). After the upgrade issue the following commands in the zebra root folder:

zebraidx init
zebraidx -g emilda update records
zebraidx commit

If everything went smoothly, restart zebra.

from 1.1 to 1.2

I. Emilda Directory, Database

Always make a backup of your database before upgrading!

The easiest way to upgrade the Emilda source is probably to move the old directory to a backup location, install the new source from the tarball and copy over required files from the old installation. Here's an example:

mv emilda emilda-1.1
tar -zxf emilda-1.2.tar.gz
mv emilda-1.2/src emilda
cp emilda-1.1/config emilda/conf/
cp emilda-1.1/MARC_config emilda/
cp emilda-1.1/MARC_defs emilda/
cp emilda-1.1/MARCsyn_config emilda/
cp -a emilda-1.1/perl/barcodes/* emilda/perl/barcodes/

Also copy/move over any other files/directories you may have in the old emilda dir that didn't come with the original tarball. If you have the Zebra database in the emilda-1.1 directory, move it to the new emilda directory. The MARC* files you copied over are only needed for the Upgrade part (setup.php) and can be safely removed after the upgrade.

Now point your Internet browser to http://your-old-emilda-address/setup.php and follow the on-screen instructions. After a successful setup your Emilda database will have been converted to the right version. Now you should edit config in the Emilda directory and remove everything except the MySQL section, as the rest is in the database now. Remember to disallow access to setup.php after completing the installation!

Note: MARC configuration has been moved to the database also but setup.php won't convert any changes you might have made to the old MARC_config file. After a successful upgrade you should log in to Emilda and modify MARC settings from the configuration panel if you made any changes to the old file.

To get languages working correctly, upgrade your locale linkage folders in the ./locale folder. You do this by going into the Emilda source folder and executing the following command:

sh bin/locales.sh

In addition you need to compile the languages to support these. This is done by going into the source folder and executing the following command:

sh bin/compile_languages.sh

II. Zebra

Upgrading Zebra is almost identical to when installing a new Emilda environment. To ensure that all files that have been updated are present on your system, we encourage you to download this tarball, and operate as follows.

1. Move your existing zebra folder to another location, but be sure not to delete it yet as this would result in you loosing all your records.
2. Extract the tarball to the same location where you had the old one, with the same name and same permissions.
3. Copy your records folder (typically records/) from your old zebra folder. If you have made any custom changes to your Emilda instance, you probably are so familiar with Zebra that you will figure out which files you need to restore from your old folder to be able to use those changes. Just make sure that also the "new" issues released will be taken into consideration. Now you can theoretically delete your old zebra folder, but it might be a good idea to hold on to it until you are certain that everything works.
4. Initialize and update your new Zebra instance by issuing the following set of commands:

   1. Go into the Zebra root folder: "cd /path/to/emilda/zebra/
   2. Init Zebra: "zebraidx init"
   3. Index the records/ folder: "zebraidx -g emilda update records"
   4. Commit results into shadow: "zebraidx commit"
   5. Start the zebrasrv-process: "zebrasrv -l /path/to/log @:9999"

   As you might notice the syntax has slightly changed, so if you have any scripts or similar that run Zebra at startup it might be a good idea to make these compatible with the new system.

from 1.1 to 1.2-alpha

I. Emilda Directory, Database

Always make a backup of your database before upgrading!

The easiest way to upgrade the Emilda source is probably to move the old directory to a backup location, install the new source from the tarball and copy over required files from the old installation. Here's an example:

mv emilda emilda-1.1
tar -zxf emilda-1.2-alpha.tar.gz
mv emilda-1.2-alpha/src emilda
cp emilda-1.1/config emilda/
cp -a emilda-1.1/perl/barcodes/* emilda/perl/barcodes/

Also copy/move over any other files/directories you may have in the old emilda dir that didn't come with the original tarball. If you have the Zebra database in the emilda-1.1 directory, move it to the new emilda directory.

Now point your Internet browser to http://your-old-emilda-address/setup.php and follow the on-screen instructions. After a successful setup your Emilda database will have been converted to the right version. Now you should edit config in the Emilda directory and remove everything except the MySQL section, as the rest is in the database now. Remember to disallow access to setup.php after completing the installation!

Note: MARC configuration has been moved to the database also but setup.php won't convert any changes you might have made to the old MARC_config file. After a successful upgrade you should log in to Emilda and modify MARC settings from the configuration panel if you made any changes to the old file.

II. Zebra

Upgrading Zebra is almost identical to when installing a new Emilda environment. To ensure that all files that have been updated are present on your system, we encourage you to download this tarball, and operate as follows.

1. Move your existing zebra folder to another location, but be sure not to delete it yet as this would result in you loosing all your records.
2. Extract the tarball to the same location where you had the old one, with the same name and same permissions.
3. Copy your records folder (typically records/) from your old zebra folder. If you have made any custom changes to your Emilda instance, you probably are so familiar with Zebra that you will figure out which files you need to restore from your old folder to be able to use those changes. Just make sure that also the "new" issues released will be taken into consideration. Now you can theoretically delete your old zebra folder, but it might be a good idea to hold on to it until you are certain that everything works.
4. Initialize and update your new Zebra instance by issuing the following set of commands:

   1. Go into the Zebra root folder: "cd /path/to/emilda/zebra/
   2. Init Zebra: "zebraidx init"
   3. Index the records/ folder: "zebraidx -g emilda update records"
   4. Commit results into shadow: "zebraidx commit"
   5. Start the zebrasrv-process: "zebrasrv -l /path/to/log @:9999"

   As you might notice the syntax has slightly changed, so if you have any scripts or similar that run Zebra at startup it might be a good idea to make these compatible with the new system.

from 1.2-alpha to 1.2-beta

I. Emilda Directory, Database

Always make a backup of your database before upgrading!

The easiest way to upgrade the Emilda source is probably to move the old directory to a backup location, install the new source from the tarball and copy over required files from the old installation. Here's an example:

mv emilda emilda-1.2-alpha
tar -zxf emilda-1.2-beta.tar.gz
mv emilda-1.2-alpha/src emilda
cp emilda-1.2-alpha/config emilda/
cp -a emilda-1.2-alpha/perl/barcodes/* emilda/perl/barcodes/

Also copy/move over any other files/directories you may have in the old emilda dir that didn't come with the original tarball. If you have the Zebra database in the emilda-1.1 directory, move it to the new emilda directory.

Now point your Internet browser to http://your-old-emilda-address/setup.php and follow the on-screen instructions. After a successful setup your Emilda database will have been converted to the right version. You may want to disallow access to setup.php after completing the installation, although, nothing harmful can be done with it after a successfull installation.

from 1.2-beta to 1.2-rc1

I. Emilda Directory, Database

Always make a backup of your database before upgrading!

The easiest way to upgrade the Emilda source is probably to move the old directory to a backup location, install the new source from the tarball and copy over required files from the old installation. Here's an example:

mv emilda emilda-1.2-beta
tar -zxf emilda-1.2-rc1.tar.gz
mv emilda-1.2-rc1/src emilda
cp emilda-1.2-beta/config emilda/
cp -a emilda-1.2-beta/perl/barcodes/* emilda/perl/barcodes/

Also copy/move over any other files/directories you may have in the old emilda dir that didn't come with the original tarball. If you have the Zebra database in the emilda-1.1 directory, move it to the new emilda directory.

Move the config file to the conf directory (mv config conf/). Now point your Internet browser to http://your-old-emilda-address/setup.php and follow the on-screen instructions. After a successful setup your Emilda database will have been converted to the right version. You may want to disallow access to setup.php after completing the installation, although, nothing harmful can be done with it after a successfull installation.

To get languages working correctly, upgrade your locale linkage folders in the ./locale folder. You do this by going into the Emilda source folder and executing the following command:

sh bin/locales.sh

In addition you need to compile the languages to support these. This is done by going into the source folder and executing the following command:

sh bin/compile_languages.sh