Before you can start developing with Interchange, you need to grasp its basic architecture. There's two high-level concepts to understand:

1. its relationship with your web server (Apache),
2. where files go

Interchange's relationship with your web server

Interchange runs as its own daemon process in parallel with Apache. It is not a CGI script, and it is not an Apache module, but it does speak through Apache using a linker that comes in either a CGI or an Apache module variant. Think of it as two peers, where Interchange is using Apache as its spokesperson, as shown in Fig 1.

Fig 1: Interchange runs separately from Apache, but it talks through

The Interchange Daemon

Interchange starts up at your server's boot time, along with other services such as Apache and Sendmail. It loads all of its catalogs, opens connections to any databases, and settles down to wait for the first web page request. But interchange never speaks to a visitor's browser directly, it waits for a linker program to do that.

The Linker

The linker is a very small and simple CGI script that Apache will call on each page request. All it does is pass page requests on to Interchange, and then pass finished HTML back to Apache to be sent to the visitor's browser. Let's say this is the URL to a page in an Interchange web site:

http://www.example.com/store.cgi/index.html

The linker is store.cgi. Apache calls it just like any other CGI script, passing a wealth of data about the environment and the circumstances under which it was called, including the full URL of the request, the visitors browser, IP address, referrer, and any POSTed data. Here's what store.cgi is going to do:

1. Open a socket connection to the Interchange daemon
2. Pass all of the data given to it by Apache
3. Wait for Interchange to do its thing
4. Take a finished HTML page back from Interchange
5. Return the HTML to Apache as its own output

There are two ways that the linker can communicate with Interchange; either through a UNIX socket, or an IP socket. Using a Unix socket (a file on the server's filesystem) is the most secure, and can be locked down with conventional Unix permissions. If, for some reason, it's not possible to do it that way, the linker can also talk through localhost on port 7786.

But the linker doesn't have to be a CGI script. Interchange comes with a second option called mod_interchange, which is an Apache module to do the same thing. As a module, it not only eliminates the overhead of invoking a CGI script, but it also eliminates the ".cgi" or "/cgi-bin" nonsense from your URL. On sites with high-volume traffic, using mod_interchange is highly recommended.

Where files go

As you start developing sites with Interchange, the distinction between a catalog's files, and everything else will become important. A single Interchange daemon is capable of hosting many web sites, which are called catalogs in Interchange's terminology.

The Catalog

Each Interchange-based web site must have a catalog, which is all of the site from Interchange's point of view. It includes all of the HTML files and all of the database tables. There's a separate directory for each catalog, and it's usually placed in the home directory of whichever user is responsible for that catalog. EG: if you're an ISP hosting many sites, the catalog directory would be in your customer's home directory. By default, Interchange assumes a single customer/user can have multiple catalogs, so it creates a directory called catalogs in the user's home directory, then creates a sub-directory within it for each catalog. Like this:

/home/cwenham
	/catalogs
		/clothing
		/electronics
		/novelties

In this example, the user cwenham is hosting three different web sites built on Interchange; clothing, electronics, and novelties. Within these three directories is all that Interchange cares about.

These catalog directories are broken down further:

• /pages - all of the HTML files
• /templates - page templates to define a sitewide look-n-feel
• /templates/components - modular components, such as a shopping-basket view, a list of product categories, etc.
• /etc - miscellaneous catalog configuration, as well as the templates for customer e-mail receipts
• /products - copies of every database table, in Tab-Delimited format
• /dbconf - table definition files for when you're using a SQL database as your back-end
• /include - fragments of common HTML and code that are used frequently in the HTML pages

There are some other directories in there which get automatically created, such as /session and /tmp, which store a visitor's session data and temporary files, respectively.

When you want to edit a page in an Interchange site, head to the /pages directory. If you need to change something about the template, go to the /templates directory.

More about templates

Recent versions of Interchange split up the /templates directory into subdirectories named after template styles. For example, Interchange comes stock with seven sample template styles. Each one contains a complete set of templates, usually themed somehow, like "blue and yellow" or "gray and orange". This makes it easier to swap out one set of templates for another with a single variable found in the catalog's master configuration.

	cp -R blueyellow mynewtheme

Images, Javascript, CSS, Movies, and Flash

To you, a complete web page will probably include images, and maybe also Flash animations, embedded movies and other media. If you're practicing good coding techniques, you've probably also moved your stylesheets and javascript into separate files to be included into the final page with LINK and SCRIPT tags. It's important that you don't try to make Interchange serve these through the linker.

Apache needs each web site to have a document root, which under most hosting arrangements is in a directory called "httpdocs" or "public_html" or in a directory under /var/www. It's in here that you'd put the linker, but you'd also put all of your images, Javascript files, CSS files, movies, Flash and so-on. Anything that isn't HTML goes in the document root and not the Catalog directory.

To reference these files from the HTML files that Interchange generates, just use their absolute or relative URL. For example:

<html>
<head>
	<title>Example Store</title>
	<link rel="stylesheet" type="text/css" href="/styles.css"/>
</head>

<body>
	<img src="/images/title.gif"/>

	... rest of page ...

The HTML page shown here is found in the catalog's /pages directory, but styles.css and /images/title.gif are both placed in the document root that Apache knows about.

Security

By default, Interchange tries to put the catalog directories outside of the web server's document root, so none of the files can be directly accessed through the web server. The idea is to force all accesses to catalog files to go through the linker, meaning it has to go through Interchange and its security model.

Interchange enforces the separation of catalogs, even when you're running more than one under the same Interchange daemon process. This means no code embedded in any Interchange page can access a file outside of the catalog's root directory. Picking up from our example above, code in /home/cwenham/catalogs/clothing would be unable to see anything in /home/cwenham/catalogs/electronics. Nor can it see anything in the web server's document root, even for the same site that the catalog belongs to.

The only exception to this rule is with symbolic links, and this is how Interchange gives catalogs the ability to see and modify images that are actually stored in the document root.

Let's say your document root is in /home/cwenham/httpdocs, and there's a subdirectory called images. Your catalog is in /home/cwenham/catalogs/clothing, and in there is a symbolic link to /home/cwenham/httpdocs/images. Interchange can now support a couple of useful features relating to images, such as uploading images through the browser (used most often in the Administration UI when adding new products), or automatically creating thumbnails.

Creating new directories

You'll want to create new directories when it comes to organizing files in a sophisticated application. All you need to ask yourself is "Does Interchange need to see these?" If the answer is yes, put it somewhere in the Catalog's directory. If the answer is no, put it in the document root Apache uses. Of course, if neither should see it, that's another matter, and you'll need to figure it out based on your security needs.

Interchange's installation directory

We wrap up with a quick look at where the Interchange daemon itself lives. There's two ways to install Interchange:

1. Somewhere in /usr, with a dedicated "interch" user account
2. In the customer's home directory

The first method is very good for sites that will have the whole server to themselves, or in cases where you have a family of related sites that'll all live on the same server. Interchange can be installed somewhere like /usr/local/interchange, or /usr/lib/interchange, and will run as a user called interch. This is how the RPM distribution tries to set it up, as well as the FreeBSD port.

The second method is best for ISPs with many customers. More than one instance of the Interchange daemon can run on the same server at the same time and they won't interfere with each other. If the server has enough resources, it's safe and recommended to unpack Interchange's TAR file in the customer's home directory, install it into a subdirectory called interchange or ic for short, and let the Interchange daemon run as that user.

The first reason is because there are circumstances when you'll want to put new files into Interchange's own installation directory. These might be Global UserTags; modules that extend Interchange's functionality, but require greater privileges than the "safe mode" Interchange would run them in if they were in the catalog's directory.

The second reason is so you can upgrade Interchange to a new version for one user without forcing everybody else's sites to upgrade at the same time. There are issues with upgrading Interchange that can affect the operation of catalogs. Having a separate copy of Interchange for each customer or site makes it possible to divide and conquer the task neatly.