Installing the SOX Shop on Web Servers

Index Ricardo index for other documentation. Click on headings to return to index.

Introduction

Description

The SOX shop is a package of backend program and frontend HTML and CGI scripts for demonstrating basic commerce models.

It is example code, rather than turnkey retail, with most programmers preferring to hack out, or in, the bits they need.

Models

These models of transaction cycle are included: SOX itself supports more, refer to the FAQ.

Versions

Release versions, latest first:

Preconditions

Installation of Shop software requires more than casual familiarity with a number of technologies, and access to a range of software products. Tick off all of these before you proceed:

Knowledge

You should have a working or passable knowledge of the following areas:

Perl and Perl Modules

Perl 5 is required to use the SOX library, preferably version 5.003. The following Perl modules must also be installed: A later version of these modules should usually work. Perl modules are generally located at CPAN , or their Dispatcher for a closer site.

Systemics Modules

In addition to the above modules, the following are also required from The Systemics Software Archive :

These should install in the normal Perl fashion, for example: 
    $ gunzip < Cryptix-1.1.tar.gz | tar -xf -
    $ cd Cryptix-1.1
    $ chmod 755 Makefile.PL
    $ ./Makefile.PL
    $ make
    $ make test
    $ make install
    ...

Systemics Applications

You will also need a working browser, configured for Systemics WebFunds. Contact us to get access to WebFunds.

Installation and Configuration

Download

After downloading and unpacking the SOX shop software the following directories should be present:

Environment

The perl-lib directory should be moved so that it is in the Perl library path, or alternatively the PERLLIB or PERL5LIB environment variable should be set to include it.

Running a Test Shop Backend

In order to test the installation so far, we can generate a test key and then configure and run the shop backend process. The most common problems will be due to missing modules or an incorrectly defined perl library path. Follow these steps, all within the admin directory:

  1. Create a test key: 
            $ cd admin
        $ ./test_key
    which will appear in the admin/test directory. You can examine this using PGP.

    Because the key generation is a complex process, this command may take a minute or so to complete.

  2. Then run config to create the directories and the configuration details modules, using the above test key: 
    	$ ./config 'test/secring.pgp' 'secret'
    where the location of the keyring and the passphrase are as printed by test_key.

    This will create a directory keys, containing a copy of the secring.pgp (and maybe pubring.pgp if it is found). Two other directories, info and accounts, will also be created.

    Also created are two Perl modules, shop_khid.pm and shop_pass.pm. The former holds all the public details, and is accessed by all programs and the CGI scripts.

    The later file, shop_pass.pm, holds only the passphrase, and is only for the backend. It should be kept secure (although the test key with passphrase 'secret' is known to all).

  3. Now run the backend: 
            $ ./shop_backend

    After displaying the shop ID, the program will attempt to communicate with the Issuer. If all is successful, the program should display 

            Waiting for requests
    and the test of the shop backend is complete. You can now hit ^C to kill the test shop.
The test key can be happily removed. It should also be ok for testing further steps, by running update_examples, as detailed below. But it won't be much good for a working shop.

Configuring the Shop

In order to install a proper shop backend, the keys (and a KHID) need to be generated by WebFunds as it will own the money. The shop is just a way-station. Do these steps:

  1. Make a new user for your WebFunds program by copying the script or batch file that starts it up, and changing the user name within that script file to something like shop (that is assumed here). When you start WebFunds up it will generate a new key, as it assumes that if its user directory is not found, a new setup is required. This key will be registered with the Issuer to make a new KHID.

  2. The new key is located in the WebFunds directory shop\userkeys. Assuming WebFunds is on a separate machine (specifically, Windows 95), transfer the key (using ftp, etc) to the machine where the shop is to be located (specifically, Unix), and run the config program on it: 
             $ cd admin
         $ ./config /tmp/secring.pgp passphrase
    As above, this will create directories keys, info, and accounts, and the Perl modules shop_khid.pm and shop_pass.pm.

  3. Now that a key has been installed, it is necessary to update various CGI scripts and HTML files. This can be done using the following command: 
             $ ./update_examples
    This updates the hard-coded HTML files (the YUGO shop) and copies into the CGI bin directory the necessary shop_khid.pm module for scripts.

  4. To start the shop backend process, nohup the shop_backend program asynchronously: 
            $ nohup ./shop_backend > shop.out &
    The progress of this process can be monitored using 
            $ tail -f shop.out

  5. The above step should be installed in your Unix rc startup scripts. Check with the system administrator on that one. One suggestion is to add a line like this to the file /etc/rc.local: 
            echo -n "Starting SOX shops:"
	perl -e '$>=1079; system "/var/httpd/shops/backends/start";'
    Where start is a script that sets up your environment and does the above nohup command.

Security. Note that the key is in two places. Each place must be secure. However, the shop is always going to be a problem, as it needs to live on a publicly accessible web machine somewhere.

To reduce risk, large amounts of funds should be swept regularly from the shop KHID to another KHID. This would be treating the shop backend as merely a shop till, and the second KHID as the back room safe.

Variations

These possible variations exist: Note that config will need to be run again if the above variations are done.

Installing the Backstop

The user's browser communicates through a Systemics proxy that converts URLs into SOX/Shop accesses. If the proxy is not configured, the URLs pass directly to the shop. In order to catch these and deliver a meaningful error message, we need to install a "backstop" (for baseball fans, or "wicket-keeper" for cricket advocates).

The following should be placed in the web servers httpd.conf file (assuming that the Apache http server is being used - other servers will differ): 

    ScriptAlias /SOX/ /your web home/cgi-bin/SOX/
The web server will need restarting before this change takes effect.

The shop file cgi-bin/SOX should be installed into the cgi-bin directory on the web server. Be sure to check that this file is executable by the web server.

In order to test that this script is installed and working, simply request the /cgi-bin/SOX/anything URL using any browser. If all is well an, error page will be displayed informing the user that their browser is not SOX compatible.

Example Shops

Some Common Elements

For all example shops, you will also need to copy the shop details module into the CGI script directory: 
    $ export WEB_HOME=my_web_dir
    $ cp cgi-bin/shop_khid.pm $WEB_HOME/cgi-bin/shop_khid.pm
    $ chmod 555 $WEB_HOME/cgi-bin/shop_khid.pm
where WEB_HOME is set to the location of your WWW directory, (this is assumed below only for documentation purposes).

There is a simple (optional) index as well: 

    $ mkdir $WEB_HOME/htdocs
    $ cp htdocs/index.html $WEB_HOME/htdocs
    $ chmod +r $WEB_HOME/htdocs/index.html

Pay-Per-View Shop - The Yugo Shop

The Yugo Shop demonstrates the sale of graphics on a per-per-view (PPV) basis.

To install the Yugo Shop, do the following:

  1. Copy the pay-per-view.cgi script from the cgi-bin directory to the web servers cgi-bin directory: 
        $ cp cgi-bin/pay-per-view.cgi $WEB_HOME/cgi-bin/pay-per-view.cgi
    $ chmod 555 $WEB_HOME/cgi-bin/pay-per-view.cgi

  2. Copy the yugos directory to the web server cgi-bin directory: 
        $ cp -R cgi-bin/yugos $WEB_HOME/cgi-bin/yugos
    If for some reason the yugos directory must be located elsewhere, then it will be necessary to modify the pay-per-view.cgi script so that the PICTURE_DIR variable contains the yugos directory.

  3. Copy the HTML files for the Yugo shop in the htdocs to somewhere where they are accessible via the web server. 
        $ mkdir $WEB_HOME/htdocs
    $ cp htdocs/pay-per-view.html $WEB_HOME/htdocs
    $ chmod +r $WEB_HOME/htdocs/pay-per-view.html

To test the shop, you will need a WebFunds user (but not the one used above for the shop). Once up and going, and loaded up with some Systemics Playdough, browse to the following URL of the HTML script (in the above, htdocs/pay-per-view.html ).

Physical Items - The Book Shop

The second example shop, the book store, is a slightly more complex shop, where an order and payment request are generated by the CGI scripts (in the pay per view example, the payment request was hard coded in the HTML file).

To install, copy the CGI scripts, and the books.pm file, from the cgi-bin directory to the web servers cgi-bin directory. 

    $ cp cgi-bin/*book* $CGI_BIN
where CGI_BIN is set to the location of your cgi bin.

Also, you will need the web page: 

    $ cp -R htdocs/books.html $WEB_HOME/htdocs
    $ chmod +r $WEB_HOME/htdocs/books.html

Now browse to the URL of htdocs/books.html assuming the above organisation. When the order is complete, if successful, you will be sent a mail message containing the purchase order.

TroubleShooting

Old Version of PGP

A shop backend startup error like this: 
	Failed to create key ring entry (Missing trust packet ())
or 
	Cannot restore from undefined data!
indicates that an intermediate version of PGP was installed. Upgrade to PGP V0.09.

Can't locate SOX/ServerInfo.pm

An error like this: 
	Can't locate SOX/ServerInfo.pm in @INC at ./shop_backend line 10.
	BEGIN failed--compilation aborted at ./shop_backend line 10.
means that the perl cannot find the shop libraries. Check the environment settings and the locations where the libraries are expected.

Deposit Fails

If the Deposit fails, one reason might be that the cash that you have in your WebFunds wallet is the wrong sort. Check that the cash required (see the logs for the shop) is the same as that sent (see the Item type in the same log). You may need to change the currency contract in admin/contracts, and run config, etc, again.

Early versions of WebFunds (about 0.22) silently carried on even if they had the wrong cash, making this difficult to debug.

Uninitialized Variable

If you see this whilst running config: 
        Use of uninitialized value at /usr/local/lib/perl5/File/Copy.pm line 84.
it appears to be nothing to worry about. An early version of Perl (?) or Copy (?) is saving a variable that isn't defined for later restoration.