Interchange Guides: Installation

DavorOcelic

This documentation is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

It is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Abstract

The purpose of this document is to guide you through the complete
Interchange installation routine.

While the concepts will be properly explained and elaborated on,
the intention is to make this document a collection of pointers
to other parts of Interchange documentation.

People installing from distribution-specific
packages (Debian GNU, Red Hat-based platforms, Gentoo, ...) do
not need a guide this comprehensive — the package maintainers
have already taken care of most of the issues.

The Guide is intended for people who want to install Interchange from
generic tarballs. You might want to prefer tarballs over
distribution-specific packages if you are either using a non-standard
platform, or want to always access the latest releases (when
distribution-specific packages are lagging behind).
So far, it seems the tarballs are the
cleanest and most preferred installation method.

Those impatient or already familiar with Unix administration and software
installations, might want to directly go unpacking the tarball and
running perl Makefile.PL; make; make test &&
make install in there.

The most common platform is probably an x86-compatible running
Linux or FreeBSD. Microsoft Windows is not (and will not be)
supported.

Perl

Since the Perl installation is crucial for Interchange setup
(and run-time performance), special attention must be given to it.
Interchange requires Perl 5.8 or newer.
Run perl -v to check your version.

Perl installations, especially from non-standard distributions or
custom, may differ in both the core functionality and modules
installed.
By far the best bet is to simply use pre-packaged Perl for your
platform. Chances are that the additional, non-standard modules required
by Interchange will also be available in your distribution.

Interchange relies on a number of non-standard Perl modules.
Installing Interchange from the generic tarball will test for the required
modules and offer an elegant way to install them.

If you want to install the modules manually, you can take
advantage of the excellent CPAN functionality and perform the work
by simply typing:

$ /path/to/perl -MCPAN -e 'install "Bundle::Interchange"'

For the complete set of modules (the required and optional ones), run

$ /path/to/perl -MCPAN -e 'install "Bundle::InterchangeKitchenSink"'

C compiler

Interchange uses the so-called "link program" to provide a link between
the web server (usually Apache) and the Interchange server. It is, in
fact, a very simple C program that is installed as a CGI script and that
passes parameters back and forth.

To compile the link program, you will need a C compiler. Most of the
time it will be GCC, but the link program is trivial and well
written so it should work with any compiler.

There also exists a variant of the link program written in Perl,
so the C compiler is not exactly mandatory (even though it is strongly
suggested). Since the link program does not contain anything specific
to the Interchange catalog it is used by, you can probably get someone to compile
it for you, and then keep copying it around to new names for each of the
catalogs (unless, of course, you want to modify compile-time link
program setttings such as socket file location or timeout values).

There are also other ways to connect the web server with Interchange; one is
using mod_interchange module for Apache 1, and
the other is using Interchange::Link for
mod_perl, but those two options will not be
considered in this guide.

Web server

Interchange is focused around the HTTP (Web) protocol.
Unless you want to run Interchange in SOAP mode exclusively (or write a
completely new interface for it), you will need a web server to
enable clients to visit your website.

Apache is probably the most commonly used web server, but you might
be interested in lighter and efficient alternatives such as
Mathopd.

In any case, we assume you have set-up (or are able to set-up) a
working web server, and know the basic configuration procedures for it.

In case of Apache, it is good to know where the Apache configuration
file is located. The catalog creation script (makecat)
recognizes the file format and can help the configurator answer some of the
questions automatically.

Know where the document root directory for your site (or virtual host)
is located. Also make sure to have write access to it.
Each catalog's
files that live in the web server space will find their place somewhere
beneath it.

Know where the cgi-bin/ directory
is located. Also make sure to have write access to it.
Each catalog's link program will find its place somewhere beneath it.

Database

It is not required, but is suggested to put your tables in some kind of
an SQL database. Interchange works with many database types, but the
mainstream ones, such as MySQL, PostgreSQL or Oracle will probably
cause no unexpected problems on first run.

Know the DSN (Data source name) string, which is what tells
the Perl DBI how to connect to the database.

Know the database administrator user name and password.

If you do not employ an SQL database, Interchange will use in-file databases
such as GNU DBM or Berkeley DB, depending on what it finds on the system.
Yet another option is SDBM, but it is severely limited in
functionality and is not selected unless explicitly specified by the
user (SDBM limits field size to 2KB which is too little to accomodate
our demo catalog and we do not consider SDBM as a realistic option).
In late 2008, SQLite support was added, but it is not used automatically.

UNIX account

As a system daemon, Interchange requires Unix username to own the files
and server processes.

Interchange can not run as root (under obvious administrator privleges, that is),
so a separate account should be created for it. UID or GID numbers are
not important, but the common usernames are interchange
or interch. Since modern Unix systems are not limited
to 8-letter usernames, there's no reason to use abbreviated forms.

For ultimate flexibility, it is a quite common approach to let every
catalog user have its own instance of the Interchange server. In that case,
make sure you don't mix up different link programs, as they become
instance-specific at compile time — compile them separately
for each user.

Installation location

Decide where to install the Interchange software. The directory will hold the
usual program files.

Also decide on the top-level directory under which you will place catalogs
you create. It is not necessary to keep them all in a common parent
directory, but it is a common setup.

Catalog name

Decide how will you call the first catalog you will create
after installation. test or
standard are common choices.

Run ./configure, which no longer performs an
installation as it used to, but simply prints proper installation
instructions (Basically, the installation routine comes down to running
perl Makefile.pl; make; make test &&
make install).

make test is probably the most important.
If you do not get an OK on all the tests ran,
you have a problem that you need to fix before moving any further.

Setting up a catalog

Interchange is based on catalogs. You need to create at least one
to start getting any results with Interchange. (There is a quirk in the
code that requires at least one catalog configured
before Interchange will run correctly).

You may wish to start with a custom catalog if you have very custom needs
or want to keep everything under your own control. However, there is the
so-called "standard" demo that ships with Interchange — it is extremely
elaborate and feature-rich for someone looking to build an Internet store,
and it allows for custom modifications. The most common
way to create a catalog based on our demo is to run our
makecat script.

Each catalog can be completely independent with different settings and
databases, or catalogs can share pages, databases, and session files.
This means that several catalogs can share the same information, allowing
"virtual malls" (although not directly out-of-the box with makecat or our
demo).

Regardless of whether you want to base your own catalogs on our demo or not,
it is strongly suggested to install the demo. It will let you
see whether your Interchange installation works, and it will also be
a nice presentation of Interchange features.

Setting up a catalog using the makecat script

There is a catalog creation script named makecat available,
that you will use to create catalogs based on catalog templates (and our
demo is, of course, organized as a template).

On the first run, makecat will ask a series of questions
to configure site-wide parameters. It will then proceed with the practical
catalog creation phase, so the first makecat session will
seem very long, and some of the questions will seem duplicated.

The makecat utility is self-documented. Each question is
accompanyed with an introduction, examples, and a reasonable Unix default.

By far the most common problem on the way to installing a working demo,
is wrong information given to the makecat program.

If you don't get it right the first time, re-run the configuration again,
and pay close attention to the prompts given.

Setting up a catalog manually

Setting up a catalog manually involves creating the necessary files and
directories, compiling the link program, and inserting a Catalog
line to the global interchange.cfg configuration file.