Installation
This document describes the installation of the "Web-based Library
Application for PICA" on a Unix server (Solaris, Linux, etc.), with
Apache as its Webserver. We assume that you are familiar with
typical Unix administration tasks and that you have some knowledge of
SQL, PHP and HTML.
Other configurations (e.g. Windows + IIS) are not supported, although
they should be possible in principle. If you succeed in getting
such a configuration to work, we would be grateful to hear from you.
Please send mail to Carsten Elsner <el@biblio.tu-bs.de>.
WARNING:
These installation notes are still very incomplete, highly beta, and
probably outdated, misguiding, or just plain wrong. Follow these
instructions, and your computer will catch fire and burn, your wive and
kids will leave you, and your car will break down. You have been
warned! ;)
Prerequisites
- Unix OS (e.g. Solaris, Linux, ...)
- Perl 5.x (www.cpan.org)
- Apache 2.x (httpd.apache.org)
Perform a standard installation of Apache.
- Sybase, *or* FreeTDS (www.freetds.org)
The Sybase libraries are required for compiling PHP with Sybase support.
You will have to edit the "interfaces" file of your sybase installation
and set up a section for your PICA LBS server (host name, port, etc):
If you do not have a Sybase
license for your operating system, you may be able to use FreeTDS
instead (untested). FreeTDS is a "open source" implementation of
the Sybase network protocol.
You will also have to add a section to your "interfaces" file in the
Sybase directory, like this, assuming your PICA server has the IP
address 1.2.3.4:
picaserver
query tcp
ether 1.2.3.4 2025
master
tcp ether 1.2.3.4 2025
If you use FreeTDS, please consult the documentation on configuration
instructions.
- MySQL (www.mysql.org)
Please use version 4.0.17 or newer. Older versions have not been tested.
WARNING:
If you use these scripts in a
production environment, please make sure that you secure
your MySQL installation!
E.g., set a password for the database administrator (DBA), drop
the "test" database, etc. The script "mysql_secure_installation",
which is part of the MySQL distribution, will perform most of these
tasks automatically.
Also, you must take care of performing regular backups ("dumps") of
your data base.
- PHP 4.x (www.php.net)
PHP must be compiled with Sybase and MySQL support, using the
"--with-sybase and "--with-mysql" configure options. You should
also compile PHP as an apache2 module, i.e.
"--with-apxs2=/path/to/apache/bin/apxs2".
Set up your httpd.conf so that Apache uses the PHP module, and so
that files with the ".php" extension are parsed by the PHP interpreter.
This is described in detail in the PHP installation manual.
NOTE: PHP 5.x is untested,
and may or may not work!
Testing your environment
Create a file "test.php" in the document root of your webserver, with
the following content:
<?php phpinfo(); ?>
Assuming your webserver has the IP address 1.2.3.5, open the URL:
http://1.2.3.5/test.php
You should see a PHP status page. Please check it, and make sure
that:
- MySQL support is enabled
- Sybase Support is enabled
If the PHP status page does not appear, or if MySQL or Sybase support
is missing, do not continue!
Check your installation and fix it!
Installation
- Create a sub-directory in your web server's document root, e.g.
"application", and unpack the contents of the installation ZIP file
into that directory.
- Create a new mysql database, and initialize the tables. The
necessary steps are, roughly (user input is in bold face):
$ mysql -p
Enter password: <administrator
password>
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 4.0.17
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>
create database application;
Query
OK, 1 row affected (0.20 sec)
mysql> exit
Bye
$ mysql -p application
< dbinit.sql
Enter
password: <administrator
password>
- You will probably have to
edit the contents of the following database tables:
- user_type_names
- user_types
and possibly others. You may edit these tables either with "mysql",
using SQL statements, or with a frontend such as phpmyadmin, see www.phpmyadmin.net.
The meaning of the tables is described in the internal system documentation.
- Now you will have to create two database user accounts that have
limited access to the "application" database.
We will call these accounts "staff" and "nostaff", but the names are
arbitrary. The necessary SQL statements are:
GRANT INSERT ON
application.persons TO nostaff
IDENTIFIED BY 'secret1';
GRANT INSERT ON application.addresses TO nostaff;
GRANT SELECT ON application.usertype_names TO nostaff;
GRANT SELECT ON application.address_types TO nostaff;
GRANT SELECT ON application.usertypes TO nostaff;
GRANT SELECT ON application.* TO staff
IDENTIFIED BY 'secret2';
GRANT UPDATE ON application.serial_number TO staff;
GRANT UPDATE, DELETE ON application.persons TO staff;
GRANT UPDATE, DELETE ON application.addresses TO staff;
Of course, you should probably use better passwords ;-)
- On the PICA LBS server, you have to create a Sybase database user
that has SELECT privilege on the "borrower" table.
- Edit at least the following PHP files:
- text.php
Text fragments that are used in the web interface.
- config.php
General configuration settings for the "non-staff" web interface.
You must adjust the name and the password for the "nostaff" database
user.
- admin/config.php
Configuration settings for the library staff's web interface
You must adjust the name and the password for the "staff" database user
as well as the Sybase database user that has read access to your PICA
database.
- When you have reached this point, everything should work
except for the "Send to PICA" functionality in the staff's web
interface (i.e. the creation of a new borrower account in the
PICA system from a applicant's data).
You can now test the system by visiting http://webserver/application
and enter a new application into the system. You may also visit the
staff's web interface at http://webserver/application/admin, where you
can view, edit or delete the new application record.
- In a production system, you must now configure your web server so
that:
- the directory "pica/" cannot be accessed at all by your
webserver>
- the directory "admin/" is only accessible by your library's
staff (e.g. password protection, IP address restriction
- the top-level directory is accessible to the world.
You may also want to enable SSL on your webserver for additional
protection.
- To enable the "Send to PICA" functionality, you will need
to set up a client/server system both on the webserver and the PICA
server.
- The perl script "pica/pica_upload_server" must be started on
the PICA server, and must run under the "lbsprod" unix account.
There is a sample init.d script "pica_upload.rc" that you may use for
this purpose.
- The perl script "pica/pica_upload_client" runs on the web
server. It is started automatically when you press the "Send to PICA"
button. Make sure that the script is executable by the the user account
that your web server is running under.
Since the script contains a password, make sure that nobody but the
webserver can read or execute the script! Otherwise, anybody who
can login to your webserver can also modify borrower accounts on your
PICA system!
- You must edit both scripts before using them. You need to
adjust these parameters:
- @ip_ok in pica_upload_server. This is an array of IP
addresses that are allowed to connect to the server. You should enter
the IP address of your web server here.
- You should change $password in both pica_upload_server and
pica_upload_client. Both passwords must match!
- You should also check and adjust the paths in
pica_upload_server.
WARNING: Note that
there is NO DATA ENCRYPTION between client and server!
In a production environment, you will probably want to set up an
encrypted tunnel (SSH, SSL) for better security.
- You can now test the "Send to PICA" functionality.
- You are done! Congratulations!
Contact
If you have problems or want to make suggestions, please contact:
University Library Braunschweig
IT Department
Martin Butkus
E-Mail: mb@biblio.tu-bs.de
Phone: +49 (0) 531 391-5066