Interchange Guides: Installation

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.


Table of Contents

Pre-requisites
Hardware platform and operating system
Perl
C compiler
Web server
Database
UNIX account
Installation location
Catalog name
Installing Interchange
Setting up a catalog
Setting up a catalog using the makecat script
Setting up a catalog manually
Starting Interchange

Pre-requisites

Hardware platform and operating system

Interchange is written in Perl, so theoretically it should run on any platform to which the Perl interpreter was ported and compiled.

See the list of systems known to run Interchange on our Supported platforms page.

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.

In fact, our demo catalog 'standard' requires use of an SQL database.

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.

Installing Interchange

We offer generic Interchange tarballs for manual installations. Visit our download page, and download tar/gz or tar/bz2 package.

Compare the MD5 and/or SHA1 sums of the file downloaded with the signatures on the download page (the signatures should match):

$ md5sum interchange-latest.tar.gz
$ sha1sum interchange-latest.tar.gz

Unpack the tarball by one of the two ways shown:

$ tar zvxf interchange-latest.tar.gz
$ gzip -dc interchange-latest.tar.gz | tar xvf -

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.

For any additional help, your best bet is to visit our community web page and drop by on IRC, or post your problem to the Users Mailing List (see Public Interchange Mailing Lists page).

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).

Interchange catalogs are structurally very simple and can even be created manually, by editing just a few files. Our document Interchange Guides: the Catalog Building Tutorial is exactly an example of a small, hand-made catalog.

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.

For a complete introduction and even ready-made files to set up a catalog from scratch, see Interchange Guides: the Catalog Building Tutorial.

Starting Interchange

For all information on starting, stopping, restarting and otherwise controlling the Interchange server, see Q:.

DocBook!Interchange!