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

                           I N T E R C H A N G E

Interchange 5.6.3

Copyright (C) 2002-2010 Interchange Development Group
Copyright (C) 1996-2002 Red Hat, Inc.

Originally based on Vend 0.2 and 0.3, copyright 1995-96 by Andrew M. Wilcox.

This program is offered without warranty of any kind.
See file LICENSE for redistribution terms.

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

Interchange is a web application server, electronic catalog and database
display system. Features include:

  * online ordering
  * real-time credit card processing hooks
  * high-end database access and retrieval with SQL support
  * product categorizing, merchandising, and discounting
  * basic customer relationship management
  * dynamic content presentation
  * content management
  * internationalization and localization support
  * real-time tax and shipping hooks
  * reporting
  * possibility of web-based administration

Interchange absolutely REQUIRES Perl 5.8.0 or later, on a Unix-like operating
system.

Interchange also requires some non-standard Perl modules to be installed on
your system. Unless you are installing from distribution-specific packages
(Red Hat, Debian, ...), the quick way to install the necessary support is to
run:

  perl -MCPAN -e 'install Bundle::Interchange'

If you would like to use a specific version of Perl, simply invoke
Perl with an absolute path to the Perl binary, such as

  /usr/local/bin/perl -MCPAN -e 'install Bundle::Interchange'

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

More information is in the following files and directories:

LICENSE          The text of the GNU General Public License (GPL), under which
                 the Interchange software is distributed.

README.rpm-dist  Notes on using Interchange when installed from RPM packages.

README.debian    Notes on using Interchange when installed from Debian packages.

README.cvs       How to access the CVS repository to track ongoing development.

WHATSNEW-*       Changes per specified version family.

UPGRADE          Instructions on how to upgrade from an earlier Interchange
                 version.

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

Major files and directories in the distribution:

Makefile.PL    Script to create a Makefile, used for installation.
               (run ./configure for usage instructions)

dist/          The distribution files, exclusive of executable
               files and modules. Includes:

               interchange.cfg.dist   Distribution-default interchange.cfg
               standard/              Demo catalog skeleton, used by makecat
               src/                   C and Perl code for CGI link programs
               lib/                   Back-end administrative interface
               code/                  Usertags and other customizable code

hints.pl       OS-specific configuration settings. None currently used.

eg/            Various helper scripts and addons.

lib/           The library modules needed to run Interchange.

scripts/       The executable files, relocated to bin/ in the install
               directory.

relocate.pl    Script that adjusts paths in scripts/ for installation into
               bin/.

test.pl        The installation test script.

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

                          I N S T A L L A T I O N

You can install Interchange as root for a multi-user system-wide setup, or
as an unprivileged user who will be the only one modifying Interchange files.

Here is the quick installation summary:

    tar xvzf interchange-5.6.3.tar.gz
    cd interchange-5.6.3
    perl Makefile.PL
    make
    make test
    make install

If you would like to use a specific version of Perl, simply invoke
perl with an absolute path to the Perl binary, such as

    /usr/local/bin/perl Makefile.PL

The build procedure asks where you'd like to install Interchange and
the name of the user account that will own the installation.

The Interchange server doesn't do much if it isn't servicing one or more
actual catalogs, so you next need to make your first Interchange catalog,
as described in the next section.

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

                                 D E M O

There is a demo catalog skeleton (called 'standard') included.

To build your own catalog from the demo, go to the directory where you
installed Interchange (default is "interchange" in your home directory,
/usr/local/interchange for root installations, or /usr/lib/interchange
for RPM installations) and run:

    bin/makecat

Follow the prompts and after restarting the Interchange server you
should be able to access the new instance of the demo catalog.

Please note that some functionality (notably the reporting features)
may not be available if you are not using an SQL database such as
MySQL or PostgreSQL.

Visit http://demo.icdevgroup.org/ to try out a live demo.

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

                         D O C U M E N T A T I O N

A documentation package is available, with documentation in many different
formats. This and other information is available at the Interchange home on
the web:

http://www.icdevgroup.org/
http://www.icdevgroup.org/xmldocs/

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

                         C O M P A T I B I L I T Y

Interchange is regularly tested on various Linux distributions and FreeBSD.
It has also been used on Mac OS X, Solaris, OpenBSD, Digital UNIX/Tru64, SCO,
AIX, and other Unix variants. It should work on any Unix with sufficiently
high Perl version number and the necessary Perl modules.

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

(end)

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

                   Tracking Interchange development in Git

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

If you don't want to wait for an official release, you can use Git to follow
the latest Interchange development.

WARNING: There may be bugs introduced at any time! Thoroughly test any changes
before incorporating. Better yet, don't use Git changes for anything but
fixing relevant bugs, and run the latest stable release.


Browse Git tree online
----------------------

To browse the Interchange Git repository online, visit:

http://git.icdevgroup.org/interchange/


Clone a local copy
------------------

See instructions on cloning and working with a local Git working copy at:

http://www.icdevgroup.org/i/dev/download


Make a distribution tar file
----------------------------

It's best to build a distribution tar file to install from, rather than
installing straight from your Git working copy. To do so:

	$ cd interchange
	$ perl Makefile.PL nocopy
	Writing Makefile for Interchange
	$ make tardist
    # much output ...
	$ ls interch*.tar.gz
	interchange-5.7.1.tar.gz


Unpack and install
------------------

Unpack the tar file and install as normal. See the README file and other
documentation for help. You should already be familiar with the Interchange
developer website at:

	http://www.icdevgroup.org/

Make sure you don't put your Git working copy at $HOME/interchange
and then install on top of it, since $HOME/interchange is the default
install directory.


Updating
--------

Follow development discussions by joining the interchange-announce and
interchange-users mailing lists.

Keep track of ongoing code changes by joining the interchange-cvs mailing
list, or watching the interchange/interchange repository in GitHub.

In many cases, the major differences in the distribution will be easily
updateable. You can copy any changed files directly to these library
directories:

	lib/Vend    (and all subdirectories)
	lib/UI      (and all subdirectories)

You should check the files:

	catalog_after.cfg     (infrequently updated)
	catalog_before.cfg    (frequently updated)
	interchange.cfg.dist  (infrequently updated)
	usertag/*             (infrequently updated)

Finally, you should check differences in the bin/* files. While they
are not as frequently updated as the lib/* files, they do change. Run
diffs against the source files in scripts/*.PL, or do another install
to a blank directory and do a diff to that.


Keeping the catalog in sync
---------------------------

If you are patterning your order methods after one of the template
catalogs, you will want to check the products/*.txt and products/*.asc
files for changes. In particular, mv_metadata.asc is used to format
and present quite a few things in the user interface. You may have
to merge the databases, but there is an automated admin UI facility
that can help you do this.


Troubleshooting
---------------

If you get a complaint that a "file is not found" when trying to do a
'make tardist' or 'make dist', that means your MANIFEST file is out of
sync with the current codebase. Just do:

	rm MANIFEST
	make manifest

Interchange Debian Packages
===========================

This document contains information about the Interchange Debian packages.

Feedback
--------

Please send your comments and bug reports to Stefan Hornburg (Racke)
<racke@linuxia.de>. He is the Interchange core developer responsible
for the Interchange Debian packages.

APT Sources
===========

Interchange Debian packages for unstable (sid) are part of the official
Debian distribution. There are no official packages for stable (etch),
oldstable (sarge) or testing (lenny).

Up-to-date Interchange Debian packages for stable are available from:

deb http://ftp.icdevgroup.org/interchange/debian interchange main
deb-src http://ftp.icdevgroup.org/interchange/debian interchange main

Debian Specific Changes
=======================

* all catalog configuration should we put into catalogs.cfg, so that
  /etc/interchange/interchange.cfg can upgraded easily

* any global usertags used locally should go into /etc/interchange/usertag
  and they'll be included if they have the extension .tag

Standard Demo
===============

For the administration of the standard demo (interchange-cat-standard
package) a secure webserver (https://) is required.

SOAP
====

The Interchange SOAP server is disabled by default. Run the following
commands to activate the SOAP server:

apt-get install libsoap-lite-perl
interchangeconfig SOAP=1
/etc/init.d/interchange restart

Other Notes
===========

* if you want to call interchange directly for catalog addition, removal,
  reconfiguration or other command line tasks, you need to use the wrapper
  script /usr/sbin/interchange either as root or as interchange user, e.g.
  /usr/sbin/interchange --reconfig=standard.

* if the selected Interchange user (default: interchange, may be changed
  through debconf) doesn't exists at installation time, it will created.
  Due to security reasons the shell for this user will be set to
  /bin/false and the password for this user will be disabled. Use
  su -s /bin/sh if you need to become the Interchange user.

CVS
===

You can build Debian packages directly from CVS with the following commmand:

dpkg-buildpackage -rfakeroot -uc -us

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

 Interchange RPM packages for Red Hat Linux and compatible operating systems

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

The Interchange RPM packages integrate Interchange with a Red Hat Linux
or compatible operating system. Files are installed in the usual Linux
Standard Base locations:

Interchange base: /usr/lib/interchange.

Executables: /usr/lib/interchange/bin.

Configuration: The global Interchange configuration file is
/etc/interchange.cfg. It is only writable by root.

Data: Catalog directories are located by default in /var/lib/interchange.

Invocation: Invocation is the normal /etc/rc.d/init.d startup method.
Interchange installs to be active in run levels 3, 4, and 5; to be killed
in all.

Logs: Logs go in /var/log/interchange. The subdirectory is needed to
allow the Interchange user ID to write/create files. A configuration file
is added to /etc/logrotate.d to do log rotation.

Run: Run files go in /var/run/interchange. This includes the UNIX-domain
socket and catalog status files. The subdirectory is needed to allow
the Interchange user ID to write/create files.

Sessions and temporary files: /var/cache/interchange.

Documentation: /usr/share/doc/interchange-5.6.3.

On a dedicated production server, it is wise to segregate as many of these
directories as possible onto their own partitions, to prevent problems if
one partition runs out of inodes or disk space, or you have a disk failure.


DEPENDENCIES

Interchange requires many Perl modules from CPAN. Many of these do not
usually come supplied with your operating system, so you will need to
install them yourself. It's best to locate RPMs for each of the needed
Perl modules and install them. To get a complete list of dependencies, do:

rpm -qp --requires interchange-5.6.3-1.*.rpm

Unfortunately, there's not currently a reliable, steady source of the latest
CPAN modules in RPM format for most operating systems. Thus the easiest way
to install them is to use CPAN to build the modules from source. First set
up CPAN and install its auxiliary modules:

perl -MCPAN -e'install Bundle::CPAN'

Then install the main modules Interchange uses:

perl -MCPAN -e'install Bundle::Interchange'

Instead you may want to install a bundle that includes many optional but
useful modules:

perl -MCPAN -e'install Bundle::InterchangeKitchenSink'


INSTALL

rpm -Uvh interchange-5.6.3-1.*.rpm
rpm -Uvh interchange-standard-5.6.3-1.*.rpm

If you have installed CPAN modules from source, rather than RPM, you'll need
to install the main interchange package without dependency checking because
RPM doesn't know about those modules you installed:

rpm -Uvh --nodeps interchange-5.6.3-1.*.rpm


STARTING/RESTARTING INTERCHANGE

Interchange, as installed from the RPM, needs a special invocation from
/usr/sbin/interchange. This is because the locations of configuration,
run, and log files differ from the places Interchange has traditionally
expected them.

As either the 'interch' user or the root user you should start or restart
interchange with this command:

/usr/sbin/interchange -r

NOTE: Contrary to other documentation, you SHOULD NOT use 'bin/restart'
or directly call 'bin/interchange' to start or restart Interchange when
you use the RPM installation.


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

                       Live Demo Catalog in RPM Format

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

There is a separate RPM that provides a live demonstration catalog called
'standard', which you may optionally use to quickly try out Interchange.
It should not be used as a basis for a real catalog; instead build
your own with the makecat tool in '/usr/lib/interchange/bin/makecat',
as described in the documentation. Do not confuse the 'standard' live demo
with the 'standard' catalog skeleton from which you are encouraged to build
your own catalog.


APACHE ASSUMPTIONS

The standard-demo RPM relies upon the following things in the Apache
installation:

-- Standard document root and CGI binary locations:

   DocumentRoot /var/www/html
   ScriptAlias  /cgi-bin/ /var/www/cgi-bin/

-- ServerName must be the same as what is revealed by `hostname` when
   the standard RPM is installed. If it is not, temporarily change the
   hostname with a command like 'hostname new.host.name' and then install
   the standard-demo RPM. Afterwards you can change the hostname back
   to normal.

-- suEXEC not enabled. If you have suEXEC enabled, you are responsible
   for changing permissions and running parameters appropriately. You
   can typically disable suEXEC by running `chmod u-s /usr/bin/suexec'.
   If you want to continue to use suEXEC, you will have to compile the
   appropriate INET mode link program and use it instead of vlink.


INSTALL

rpm -Uvh interchange-standard-demo-5.6.3-1.*.rpm


USING THE DEMO

Once installed, you should be able to access the demo catalog like this
(using your own hostname, of course):

http://hostname/standard/

The initial administrative user name is "interch", and the password is
"pass". Change the password as soon as possible.


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

                              More information

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

http://www.icdevgroup.org/ has complete documentation, user mailing
list information, and other resources.