$Id: INSTALL,v 1.23 1999/04/19 13:20:50 ecila40 Exp $

The Catalog home page is http://www.senga.org/

Quick start (assuming you have installed MySQL and Perl):
---------------------------------------------------------
          #
          # Extract the distribution
          #
          tar -zxvf Catalog-*.tar.gz
          #
          # Go to the distribution directory
          #
          cd Catalog-*
	  #
	  # Install dependent modules (assuming you've installed
	  # the CPAN module).
	  #
	  MYSQL_HOME=/usr IN_MYSQL_DISTRIBUTION=1 \
	  DBI_DB=mysql DBI_DSN=dbi:mysql:mysql DBI_USER=root DBI_PASS=passpass \
	    perl -MCPAN -Ilib -e 'force install Bundle::Catalog'
          #
          # replace /home/httpd/cgi-bin by your cgi-bin directory
          # replace /home/httpd/html by the directory where you put your
          #     HTML pages.
          #
	  mkdir /home/httpd/html/Catalog
          HTMLDIR=/home/httpd/html/Catalog HTMLPATH=/Catalog \
             CGIDIR=/home/httpd/cgi-bin CGIPATH=/cgi-bin \
	     USERID=nobody \
	     MYSQL_USER=root MYSQL_PASSWORD=passpass MYSQL_BASE=mysql \
             perl Makefile.PL
          #
          # Install the software
          #
          make install
          #
          # Read the Setup chapter in the documentation. It will 
          # teach you how to configure catalog and create your first catalog.
          #
          netscape http://www.mymachine.org/Catalog/catalog_toc.html
          #
          # Go to URL http://www.mymachine.org/cgi-bin/Catalog?context=ccontrol_panel
          # to get the Catalog Control Panel.
          #
          netscape http://www.mymachine.org/cgi-bin/Catalog?context=ccontrol_panel

Requires: 
---------
          At the end of this file you will find scripts that will help
          you install these components on specific plateforms. The 
          distributions packages of all these specific versions can be 
          found on the senga site at http://www.senga.org/download.html.

          To build the software you will need:

          perl5.005_02 or higher (http://www.perl.org/)
          mysql-3.22.19a or higher (http://www.tcx.se/)

	  Catalog depends on other Perl modules. You can either install them
	  yourself or use the Bundle facility as shown in the Quick start
	  section. Here is a complete list of the modules needed to run
	  Catalog with minimal version number. All of them may be found on 
	  CPAN (http://www.perl.com/CPAN/).

	  DBI 1.02 - Database independent interface for Perl

	  DBD::mysql 2.0210 - mysql drivers for the Perl Database Interface (DBI)

	  MD5 1.7 - Perl interface to the MD5 Message-Digest Algorithm

	  CGI 2.46 - Simple Common Gateway Interface Class

	  XML::Parser 2.22 - parsing XML documents

	  XML::DOM 1.19 - building DOM Level 1 compliant document structures

	  Unicode::String 1.20 - String of Unicode characters

	  Unicode::Map8 0.05 - Mapping table between 8-bit chars and Unicode

          An HTTP server (Apache for instance) running on your local machine.
	  If you want really good performances you must build Apache with
	  mod_perl. See the INSTALL.apache file for instructions.

          To build the documentation (optional) you will need:

          HTML format : texi2html-1.51a or any version handling @image
          PS format : texi2dvi, TeX, dvips
          Emacs info format : makeinfo-3.12 or higher

Configuration:
--------------

          tar -zxvf Catalog-*.tar.gz

          cd Catalog-*

          perl Makefile.PL

              At this point you can either answer the questions or
                pre-define the answers using the following environment 
                variables:

              CGIDIR for the path of the directory where the cgi-bin 
                     programs will be installed.
	      CGIPATH for the location of the cgi-bin scripts when browsing
	               from a navgigator. Typically if you've set CGIDIR to
	               /home/httpd/cgi-bin this will be /cgi-bin.
              CONFIG_DIR If not specified it will default to CGIDIR. 
                     CONFIG_DIR is the path of the directory where the default 
                     configuration files will be installed. Existing
                     configuration files, if any, will be preserved. 
                     The cgi-bin programs will only be able to find the
                     configuration files if they have the CONFIG_DIR variable
                     properly set in their environment.
              HTMLDIR for the path of the HTML directory where the
                      HTML material (doc, images...) will be installed. Note 
		      that images in the documentation will only be included if
	              you have texi2html version 1.51a (by default on GNU
	              Linux RedHat 5.2, if you installed everything from 
	              the distribution).
	      HTMLPATH for the location of the Catalog material when browsing
	               from a navgigator. Typically if you've set HTMLDIR to
	               /home/httpd/html/Catalog this will be /Catalog.
              INFODIR for the path of the info directory where the
                      documentation will be installed.
              USERID The user id of the HTTP daemon. The configuration files
                     must have the same owner because the HTML interface
                     must be able to modify them.
	      MYSQL_BASE name of the MySQL database that will be used.
	      MYSQL_USER name of the user for authentification when connecting
		     to the MySQL server (--user option).
	      MYSQL_PASSWORD password of the user for authentification when
		     connecting to the MySQL server (--password option).
	      MYSQL_HOST host name of the machine where the MySQL server is
		     located (--host option).
              MYSQL_PORT TCP/IP port to use to connect to the server, if not
		     the default (--port option).
	      MYSQL_UNIX_PORT file name of the socket file to use when 
	             connecting to a server on the local 
	             machine (--socket option).
	      DOC_HTML if set to 'yes' format documenation in HTML, if set to
		     'no' do not format. If conversion utility is missing, skip
		     formating anyway. Default is yes.
	      DOC_PS if set to 'yes' format documenation in Postscript, if set 
		     to 'no' do not format. If conversion utility is missing, 
		     skip formating anyway. Default is no.
	      DOC_INFO if set to 'yes' format documenation in Emacs info, if
		     set to 'no' do not format. If conversion utility is 
		     missing, skip formating anyway. Default is no.

	      Alternatively you can hand edit the conf/install.conf and
	      conf/mysql.conf files. The mysql.conf file contains the values
	      associated to the environment variables starting with MYSQL_
	      and the install.conf file contains all the others.

	      When the Makefile.PL is executed, it reads the conf/install.conf
	      and conf/mysql.conf files and re-use existing values as 
	      defaults. An environment variable will override the corresponding
	      value found in the files. If a value is specified using an
	      environment variable, the interactive mode is disabled for
	      this value. At completion the the conf/install.conf and 
	      conf/mysql.conf files are updated with the new values.

	      If the configuration contained in the conf/install.conf and 
	      conf/mysql.conf files is correct and you simply want to
	      execute Makefile.PL again (after a make clean, for instance)
	      you can completely skip user interaction using the following

			USE_DEFAULTS=1 perl Makefile.PL

	  make 

	  make test

          make install

Plateform specific:
-------------------

These sections are helpers to install the software required before
you can use Catalog. The distributions packages of all these specific 
versions can be found on the senga site at http://www.senga.org/download.html.

RedHat 5.2
----------

#
# Run these as root user
#
#-------------------------------------------------------------------------
#
# Build perl (RedHat 5.2 is shipped with perl5.004_04 and we need perl5.005_02)
# Get file from http://www.perl.com/CPAN/src
#
tar -zxf perl5.005_02.tar.gz ; \
	cd perl5.005_02 ; \
	sh Configure -des ; \
	make ; \
	make install
#
# Check that we are using the just compiled perl
#
perl -v
#
# Install CPAN module
# Get file from http://www.perl.com/CPAN/modules/by-module/CPAN/
#
# You will be asked a lot of questions and can safely use the defaults.
#
tar -zxvf CPAN-1.48.tar.gz ; \
	cd CPAN-1.48 ; \
	perl Makefile.PL ; \
	make ; \
	make install
#-------------------------------------------------------------------------
#
# Install MySQL 
#
# First uninstall older release
#
rpm -e MySQL-devel
rpm -e MySQL
rpm -e MySQL-client
#
# Get files from ftp://ftp.tcx.se/pub/mysql/Downloads/MySQL-3.22/
#
rpm -ivh MySQL-client-3.22.19a-1.i386.rpm
rpm -ivh MySQL-3.22.19a-1.i386.rpm
#
# Set up permissions as suggested by the installation.
#
/usr/bin/mysqladmin -u root password 'passpass'
#
# Finish MySQL installation
#
rpm -ivh MySQL-devel-3.22.19a-1.i386.rpm
#-------------------------------------------------------------------------
#
# Extract Catalog distribution
#
gtar -zxvf Catalog-*.gz
cd Catalog-*
#
# Install Perl modules needed by Catalog
# (change root/passpass to your real user/password)
#
MYSQL_HOME=/usr IN_MYSQL_DISTRIBUTION=1 \
DBI_DB=mysql DBI_DSN=dbi:mysql:mysql DBI_USER=root DBI_PASS=passpass \
 perl -MCPAN -Ilib -e 'force install Bundle::Catalog'
#
# Create HTML repository 
#
mkdir /home/httpd/html/Catalog
#
# Configure catalog (change root/passpass to your real user/password)
#
HTMLDIR=/home/httpd/html/Catalog HTMLPATH=/Catalog \
 CGIDIR=/home/httpd/cgi-bin CGIPATH=/cgi-bin \
 USERID=nobody \
 MYSQL_USER=root MYSQL_PASSWORD=passpass MYSQL_BASE=mysql \
 USE_DEFAULTS=1 \
 perl Makefile.PL
#
# Build
#
make 
#
# Test
#
make test
#
# Install
#
make install

Solaris 2.6
-----------
#
# These instructions assume that you're a normal user on a Solaris 2.6
# system, without root privileges. The instructions do not differ much
# if you have root access.
# gtar stands for GNU tar (found on ftp://prep.ai.mit.edu/pub/gnu)
#
# Add our local bin directory in the path
#
export PATH=$HOME/local/bin:$PATH
mkdir $HOME/local
#-------------------------------------------------------------------------
#
# Build perl 
# Get file from http://www.perl.com/CPAN/src
#
gtar -zxf perl5.005_02.tar.gz ; \
	cd perl5.005_02 ; \
	prefix=$HOME/local ; \
	LD_LIBRARY_PATH=:`pwd`:$LD_LIBRARY_PATH \
	sh Configure -des -Dprefix=$prefix -Dlocincpth=$prefix/include -Dloclibpth=$prefix/lib ; \
	make ; \
	make install
#
# Check that we are using the just compiled perl
#
perl -v
#
# Build texi2html
# Get file from http://www.senga.org/download.html
#
cp texi2html $HOME/local/bin
#
# Edit $HOME/local/bin/texi2html and change
# the first line to $HOME/local/bin/perl
#
chmod +x $HOME/local/bin/texi2html
#-------------------------------------------------------------------------
#
# Install CPAN module
# Get file from http://www.perl.com/CPAN/modules/by-module/CPAN/
#
# You will be asked a lot of questions and can safely use the defaults.
#
gtar -zxvf CPAN-1.48.tar.gz ; \
	cd CPAN-1.48 ; \
	perl Makefile.PL ; \
	make ; \
	make install
#-------------------------------------------------------------------------
#
# Install MySQL 
#
# Get files from ftp://ftp.tcx.se/pub/mysql/Downloads/MySQL-3.22
#
cd $HOME/local ; \
	gtar -zxf mysql-3.22.19a-sun-solaris2.6-sparc.tar.gz ; \
	ln -s mysql-3.22.19-sun-solaris2.6-sparc mysql ; \
	cd mysql ; \
	scripts/mysql_install_db ; \
	bin/mysqld --basedir=. --datadir=data & \
	./bin/mysqladmin -u root password 'passpass'
#
# Add mysql bin directory to your path
#
export PATH=$HOME/local/mysql/bin:$PATH
#
# Specify the location of the MySQL installation to
# the MySQL server.
#
(
 echo "[mysqld]"
 echo "basedir=$HOME/local/mysql"
) > $HOME/.my.cnf
#-------------------------------------------------------------------------
#
# Build Apache
#
# Get file from http://www.apache.org/dist/
#
gtar -zxvf apache_1.3.4.tar.gz ; \
	cd apache_1.3.4 ; \
	prefix=$HOME/local ; \
	./configure --prefix=$prefix ; \
	make ; \
	make install
#
# Edit $prefix/conf/httpd.conf and change the user and group
# 
# User <your user id>
# Group <your group name>
#
# uncomment the line starting with ServerName
#
# ServerName www.yourmachine.org
#
# Edit $prefix/conf/srm.conf and uncomment the ScriptAlias line
#
# ScriptAlias /cgi-bin/ $HOME/local/cgi-bin/
#
# Run the server, by default on the 8080 port 
# (http://www.yourmachine.org:8080/)
#
$HOME/local/bin/apachectl start
#-------------------------------------------------------------------------
#
# Extract Catalog distribution
#
gtar -zxvf Catalog-*.gz
cd Catalog-*
#
# Install Perl modules needed by Catalog
# (change root/passpass to your real user/password)
#
MYSQL_HOME=$HOME/local/mysql IN_MYSQL_DISTRIBUTION=1 \
DBI_DB=mysql DBI_DSN=dbi:mysql:mysql DBI_USER=root DBI_PASS=passpass \
 perl -MCPAN -Ilib -e 'force install Bundle::Catalog'
#
# Create HTML repository 
#
mkdir $HOME/htdocs/Catalog
#
# Configure catalog (change root/passpass to your real user/password)
#
HTMLDIR=$HOME/local/htdocs/Catalog HTMLPATH=/Catalog \
 CGIDIR=$HOME/local/cgi-bin CGIPATH=/cgi-bin \
 USERID=$LOGNAME \
 MYSQL_USER=root MYSQL_PASSWORD=passpass MYSQL_BASE=mysql \
 USE_DEFAULTS=1 \
 perl Makefile.PL
#
# Build
#
make 
#
# Test
#
make test
#
# Install
#
make install

--------------------------------------


Loic Dachary
loic@senga.org
http://www.senga.org/
