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.

DocBook! Interchange!