Instructions for setting up a fresh, Emilda 1.2.x environment
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.
- 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.
- 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.
- 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.- 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.
- 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.
- 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.
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.
- 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/)
- 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. 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;
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.
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)
- 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.
After completing all the sections above it is time for fine-tuning.
- 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.
- 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.
- 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.shIn 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- 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.
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.
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).
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.
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.