Products | Scripts | Services | Tutorials | Books | Links | Contact | Bulletin Board

The CITY Shop

Overview | Concept | Licensing | Demo/Download | Installation | Gallery | Last Updates | FAQ

Templates | Views | Engines | Libraries | Main Setup | Shop Setup | Database | Session | Shipping

Installation

Prerequisites

You will need the following data before attempting to install the script:

  • Operating System
  • Web Server software / version
  • the full path to your cgi-bin directory
  • the path to Perl on the system
  • the Sendmail (or compatible) calling method/path
  • read this file to the end.

Once you have these, your installation will be of one of these types:

  • Unix-type system (Linux, BSD, Solaris,...)
  • Microsoft platforms (WinME/WinNT/Win2000)

We would like to repeat: read this file to the end. This is not the daily paper, nor an e-zine. Going step by step through this file, will help you install the shop properly. For installation pitfalls, we provide a FAQ list.

Microsoft users - best recommended setup

If you host or develop on Win98/WinME/NT/Win2000, and want a reliable package, we have a case study, of how to install Apache, mod_perl, and configure the system optimally.

You can look this up in our docs page, under "Install a Win32 box with Apache"

Unix users - experimental install method

We put together a Perl script to automate the installation of the shop, click here to check it out.

Before you start

Be sure you understand the way the security is set up on your system (web server). Some folders contain sensitive data, and these folders should NOT be accessible to the browsing user. As an example, if after you installed the shop, enter in the browser (using the right domain and path):

 http://www.mydomain.com/cgi-bin/store/shops/Data_files/product.db

If you see the product database, that is BAD! Some people put in there a .htaccess file, and think that this solves it, but we strongly suggest contacting your ISP and have them protect properly your entire cgi-bin. If your ISP uses Apache, then that is very simple, making the script alias to a directory outside of the web root. Other web software have similar mechanisms.

If you just want to see if that is protected or not, before installing the shop, create under cgi-bin a folder named "store",. flag it 777, upload there a test file with some text in it, named test.txt, then try in your browser:

 http://www.mydomain.com/cgi-bin/store/test.txt

Again, if that file shows in the browser, you need to review your security settings.

The manager.cgi uses CGI.pm for the file upload. However, since there are a lot of broken CGI.pm versions out there, we went the extra length and packaged WITH the shop the 2.752 version, which is the last cross-platform reliable version. The new 3.01 has the file upload broken, the previous ones have other problems.

If you have troubles with your hosting

We strongly recommend checking all the features offered by your ISP, before building up services that might not be working completely when you are done. Here is a checklist of what your ISP should offer:

  • your own CGI directory, with FTP access to it.
  • Perl 5.005 or higher. The shop script requires at least Perl 5.005
  • Net::SSleay, or LWP::UserAgent together with Crypt::SSLeay. These are almost always needed for the payment gateway.
  • Your ISP should offer you for free, the installation of CPAN modules when you ask for it. A typical module, which is recommended, is Mail::Sender, that you will need for emailing orders and other information. This module is not absolutely needed, but allows a lot of things to be done easier.
  • access to the server access and error logs. Some ISP's email you those periodically, but in order to make an efficient debugging of the scripts, you will need direct access to those files.
  • the ability to connect to another server, using a CGI script (needed for ShippingUPS and the payment gateway. Some ISP's deny that service, a typical shot in the foot.
  • your secure server, or your cgi-bin directory aliased to the ISP's secure server. The secure server should be on the same physical machine. We warn the people that are offered secure hosting on a different machine, that there is no way you can access your session and your cart from a remote machine.

Also, we recommend getting hosted on a Unix/Linux box. Hosting on Microsoft platforms is bound with peril, given the multitude of backdoors and security issues in Microsoft software. If you set your own server and still want to use Microsoft as a platform, we recommend then at least to say NO to IIS, and install Apache instead.

All this cannot go without making a recommendation for an ISP that offers all of these features, and more, please check http://www.ultra-comm.com/ .

 

 

1. Upload the files to your web server

If you looked through the zip/tarred file, you might have noticed the presence of the folder "images". With the exception of this folder, all other files have to be uploaded in ASCII mode. This is absolutely necessary on Unix platforms.

The "images" folder needs to be uploaded separately, in the web root, since leaving it in the script directory will render it inaccesible for the browsers. Of course, you will have to edit the "This.pm" to contain the correct path to the images folder, as follows (this path refers to the web root):

  -SHOP_IMAGE_PATH => $ImageRootPath.'/images/shops/city',

If you plan renaming the default shop, from "city" to something else, we recommend first getting the standard shop running, and rename the folder afterwards. You wil have to modify all hashes related to shops in the This.pm.
As you see, we use the variable $ImageRootPath, to make it easier for people that share a document root for multiple shops. If this is not your case, please use an absolute path instead, as in the example:

  -SHOP_IMAGE_PATH => '/home/myaccount/www/images/shops/city',

 

 

2. Set the correct Perl path in the main script

You have to make sure that the first line in the main scripts (store.cgi and manager.cgi) has the path to perl, in the form:

#!/usr/bin/perl -wT

For Microsoft platforms, you will enter here the path to Perl and the correct drive. Note that some web servers ignore this (i.e. Netscape Enterprise), but you should let it there anyway.

#!c:/apps/perl/bin/perl.exe -wT

Note to the parameters passed to Perl in the first line:

the "w" parameter:
prints warnings about variable names that are mentioned only once, and scalar variables that are used before being set. Also warns about redefined subroutines, and references to undefined filehandles or filehandles opened read-only that you are attempting to write on. Also warns you if you use values as a number that doesn't look like numbers, using an array as though it were a scalar, if your subroutines recurse more than 100 deep, and innumerable other things.

the "T" parameter:
forces "taint"' checks to be turned on so you can test them. Ordinarily these checks are done only when running setuid or setgid. It's a good idea to turn them on explicitly for programs run on another's behalf, such as CGI programs

For more info about these parameters, please consult a Perl book, like:
Programming Perl (2nd Edition) by Larry Wall, Tom Christiansen, Randal L. Schwartz, Stephen Potter

 

 

3. Assign then, the right path to the library directories, as follows:

unshift @INC, 
        '/var/www/cgi/city/store/Library',
        '/var/www/cgi/city/store';
use lib qw (./Library);

For Microsoft platforms, these paths will have to contain the correct drive letter and path:

unshift @INC, 
         'w:/cgi/city/store/Library',
         'w:/cgi/city/store';
use lib qw (./Library);

They are all needed, to make sure that your script will work under different versions of Perl and Perl accelerators (ModPerl, PerlEx).

If you use Microsoft IIS or Apache with ModPerl on NT, you will also need to change the working directory to the script directory. For that, you will need to insert the following line, as the second line of the script (or somewhere at the beginning):

BEGIN{chdir("w:/cgi/city/store")}

 

 

4. Decide on the use of internal routines, or of CGI.pm (optional)

Normally, the script ist executing a custom input processing routine, which is fast and reliable. You will not need to do anything if the script works as it is.

The following is optional, the script will run without modifying it:

If you want to use CGI.pm instead, and implement some cookie processing or other functions with it, you should uncomment the following lines:

use CGI qw/:standard/;
CGI::POST_MAX = 131072;
CGI::DISABLE_UPLOADS = 1;

The lines 2 and 3 define parameters for the operation of CGI.pm. If you plan to post content like file upload, you will need to specify the size limit of the uploaded file, and also to enable the file upload in the first place. The specified value (16384) corresponds to the number of bytes to accept via POST - 2^14 (roughly 16KB).
You will also have to enable the flag at the beginning of the _Run() routine:

$UseCGI = 1;

Currently the shop.cgi does not implement file upload in any of the available routines. The file upload is available in the manager.cgi, and you need to use CGI.pm for that.

 

 

5. Decide if you want to use ModPerl or other Perl accelerator (Optional)

We will discuss the implementation of ModPerl in detail later; if you don't know what to do, ignore this step and use default values.

The following is optional, the script will run without modifying it:

Also at the beginning of the _Run() routine, you can define the mode that your script is running. For example, you can have a development system that uses both Perl and ModPerl, and you want an easy way to switch back and forth between the modes. This feature is especially useful, considering that you cannot use ModPerl when you are making changes in the script, since the code once compiled, will run from memory instead of accessing the disk for your latest version.

If you want to use ModPerl, set the following variable on 1:

my $UseModPerl = 1;

Using ModPerl will eventually require another aliased path in the web server configuration, which you can declare in the main setup file (This.pm):

my $BasePath = $UseModPerl ? '/mod-cgi/store': '/cgi-bin/store';

As you can see, setting the value on "1" will determine the value of $BasePath to be "/mod-cgi/store". Personally I run the ModPerl scripts in a separate directory, since they need special attention compared with the regular Perl scripts. I strongly advise using the parameters "w" and "T" in the first line of script, if you use ModPerl.

Important note about mod_perl: if you run your scripts under it, they will be loaded in memory; any changes you make to the code will require a web server restart, for mod_perl to see the correct version.

 

 

6. Set the paths in the main configuration file

In the main configuration file (Library/This.pm) there are a few other things that you will have to set up. First one, is the root path to use in requires:

my $RootPath = '.';

Depending on your system, you might need to enter here a root path like:

my $RootPath = '/var/www/cgi/store';

The Microsoft version of the above will be:

my $RootPath = 'w:/cgi/city/store';

If your system supports it, you can use a relative path instead, assigning the value: ".". I run this on NT, Win2000, RedHat and BSD with a relative path, and works just fine.

Then, you need to define the base path to the script. Enter here the correct domain name that will be used to address the script:

  -COMMON_BASE_URL => 'http://www.mydomain.com',

If you do not want to use a fully qualified DNS name, you can assign it an empty value instead.

Every shop has a hash of parameters, that can be set to override the defaults:

 'city' => {
  -SHOP_PATH              => $RootPath.'/shops/city',
  -SHOP_WEB_ROOT_PATH     => 'w:/http/city/www',
  -SHOP_IMAGE_PATH        => $ImageRootPath.'/images/shops/city',
  -SHOP_DATA_PATH         => $RootPath.'/data/shops/city',
# -SHOP_BASE_URL          => 'http://www.mydomain.com',
  -SHOP_SECURE_BASE_URL   => 'https://www.nightmedia.net/mydomain',
# -SHOP_MANAGER_URL       => $BasicURL.$ScriptBaseDir.'/manager.cgi',
# -SHOP_SCRIPT_URL        => $BasicURL.$ScriptBaseDir.'/store.cgi',
  -SHOP_SECURE_SCRIPT_URL => 'https://www.nightmedia.net'.$ScriptBaseDir.'/store.cgi',
  -SHOP_IMAGE_URL         => '/images/shops/city',
# or, if your image path is different in secure mode:
# -SHOP_IMAGE_URL => $UseSSL ? '/city/images/shops/city' : '/images/shops/city'
},

For every shop you can define a separate URL, both for the http and the https (secure) mode. This will allow you to use your ISP secure certificate, if you do not have one for your domain. Make sure your ISP aliases to the same cgi-bin used by the non-secure server.

As you can see in the example above, some use the default paths $ImageRootPath and $RootPath, while others define an absolute path. There is also built in an example of how you can use a different image base URL if you are using a secure server.

 

 

7. Set the mail parameters:

Recommendation for all systems:

We recommend the usage of the Perl module Mail::Sender. If you are hosted with some ISP, ask them to install the module from CPAN.

Should you run your own server, here is how you do it:

Unix:

open a telnet session to your server, then su to root. Enter at the prompt:

perl -MCPAN -e shell

At the resulting prompt, enter:

install Mail::Sender

Windows:

open a command prompt (make sure you have write rights to the directory where Perl is installed. Change directory to the directory where you have Perl installed (the example is for Activestate Perl). Enter the following commands: 

cd c:\Perl\bin
ppm

Again, at the resulting prompt, type:

install Mail::Sender

once installed, make sure you set in the This.pm:

  -MAIL_PROGRAM_TYPE => 'mailsender',
  -MAIL_SMTP_HOST    => 'mail.mydomain.com',

Use for the SMTP host key, the mail server of your ISP.

Alternate methods:

Unix systems:

The first line has to have the value "unix", which is case-sensitive.
Depending on the path of sendmail, if sendmail is NOT in the environment path, you might want to enter in the second line a full path to the executable. From platform to platform, you might need some extra command-line parameters to sendmail, which you will include in the string:

  -MAIL_PROGRAM_TYPE => 'unix',
  -MAIL_PROGRAM_PATH => 'sendmail -t',

Microsoft systems:

The first line has to have the value correspondent to the SMTP daemon you use on your system.

The programs implemented currently are: "ntsendmail" and "blat".
The product pages for the listed programs, can be found under:

ntsendmail - http://www.indigostar.com/sendmail.htm
blat - http://www.interlog.com/~tcharron/blat.html

If you want to use other Sendmail substitute on NT, go on, customize the SendMail.pm, or let me know of the location of the program you use, and I will build a section for it. 

  -MAIL_PROGRAM_TYPE => 'ntsendmail',
  -MAIL_PROGRAM_PATH => 'w:/cgi/scripts/sendmail -t -n',
#  -MAIL_LOG_PATH => './logs/sendmail.log', # redefined in the shop setup
  -MAIL_SMTP_HOST => 'mail.mydomain.com',

As you see, there is a commented-out line, that points to the mail log being defined in the shop setup. Leave this line commented out, unless you want to keep a common mail log for all the shops, in which case you should provide a complete path to the log file.

The last line is pointing to the SMTP relay host that will be used by the executable to relay out the email. This can be the localhost if you are running some SMTP daemon on the machine already (might work well with Microsoft Exchange, it does work with Netscape Messaging, others need to be tested). If you are not running anything on the same machine, you can use the SMTP server of the ISP that hosts you, and make sure they allow you to relay mail through their server.

You will have to edit the ShopSetup.pm file from your shop directory, and enter the correct email addresses to be used for order processing:

-MAIL_ORDER_FROM_ADDRESS     => 'me@mydomain.com',
-MAIL_ORDER_REPLY_TO_ADDRESS => 'me@mydomain.com',
-MAIL_SITE_ADMIN             => 'me@mydomain.com',

 

8. Set the file and directory attributes (Unix users)

This step is for the Unix users.

You will need to set the file and folder ownership and attributes, to allow your web server to run the script properly. Depending on what system you run, your ISP will allow you to chown files or folders, or even set them up for you, as you require.

Regardless of the method, you will need to set the file and folder attributes, as follows:

chmod the store.cgi and the manager.cgi as "755"

chmod the following folders as "777":

  • pgp
  • gpg
  • images/shops/city
  • images/shops/city/products
  • data/shops/city
  • shops/city/Data_files
  • shops/city/Logs
  • shops/city/Export
  • shops/city/Import
  • shops/city/Upload
  • shops/city/Upload/data
  • shops/city/Logs/adminorders
  • shops/city/Logs/orders
  • shops/city/Sessions
  • shops/city/User_carts

chmod all the files in the following directories as "666":

  • images/shops/city
  • images/shops/city/products
  • shops/city/Data_files

All other files and folders can be left as default, which is usually "644".

 

9. Configure PGP or GPG for the secure emailing of order payment data

Regardless of the operating system, we want to point to a few aspects of encryption.

If your ISP offers you PGP support, they might have to create the keys for you, and provide you with the path to the private and public keyrings. Some ISP's keep only one database, and all you will get in this case will be a key ID, to which you have to provide a password in advance. PGP is not a free software.

Last time I checked, Network Associates wants you to pay $5500 for the server version of the software, which is plain prohibitive. Fortunately, there is a free alternative to PGP: use the GnuPG. The GnuPG web site is located at http://www.gnupg.org/ , where you can dowload precompiled binaries for your operating system. Even if you only have a cgi-bin directory, it is simple to upload the binaries for your operating system to the server, flag the gpg as executable and then modify the ShopSetup.pm to point to the right directory.

It is good when your ISP installs it for you, because that way the keys are more secure, being out of your path.

Once you have the software installed, you have to make a couple changes in the ShopSetup.pm. Add or modify the following key to have the correct entries:

For PGP, considering you have a Unix installation:

-SHOP_ENCRYPTION_SETUP => {
  'pgp' => {
    -PGP_PUBLIC_KEY_NAME => 'The CITY',
    -PGP_BINARY_PATH => '/usr/bin/pgp',
    -PGP_CONFIG_PATH => '/usr/home/myaccount/cgi-bin/store/pgp',
    -PGP_TEMP_DIR => $LogPath,
    -USE_IPCOPEN3 => 1,
  },
},

For GPG, considering you have a Win32 installation:

-SHOP_ENCRYPTION_SETUP => {
  'gpg' => {
    -GPG_PUBLIC_KEY_NAME => 'The CITY',
    -GPG_BINARY_PATH => 'c:/apps/gnupg/gpg.exe',
    -GPG_CONFIG_PATH => 'w:/cgi/city/store/gpg',
    -GPG_TEMP_DIR => $LogPath,
    -USE_IPCOPEN3 => 0, # will not work on NT
  },
},

Here are a few useful links related to GnuPG:

http://www.gnupg.org/frontends.html A list of email front-ends for GnuPG

http://www3.gdata.de/gpg/index.html An Outlook plugin. The site is german, but they have an english download as well.

http://www.winpt.org/gpgoe.html An Outlook Express plugin

http://www.winpt.org/ A "privacy tray" for the desktop

We recommend the use of the GPG for the Win32 environments, since we got it to work easily. We found impossible to configure the PGP on the Win32 platform, and place the keys in your own directory. Of course, you can set the home directory in an environment variable, and it works when called by hand, but its value dissapears when running the routine from the web server.

We tried on Win32 with the version 7.0 (latest) of the PGP server. If you try with an older version, you might get it running, but we found it's not worth the trouble. GPG has an command line option where you can pass the home directory directly, which makes the implementation very simple and reliable.

Also, using the IPC::Open3 on the Win32 platform will hang the encryption process. We think that this is caused by the defective forking in the Activestate software. Just use the temp file method, it works.

The next thing to do is to define/set the following key in the ShopSetup.pm:

-MAIL_ENCRYPT_METHOD => 'gpg',

This is enough, to have it encrypt the payment information, in the ShopOrderLib.pm. You can find more information in the module documentation.

 

Unix users - experimental install method

Since the attribute setting is quite an intensive task, we put together a script that does it for you. The script is named "setupstore.cgi".

Here is the way things work:

you start with your web directory on your web server, let's say it is "/usr/home/myuserid" and that your cgi-bin directory is right underneath, as: "/usr/home/myuserid/cgi-bin".

The first thing, you copy the tar file in your cgi-bin directory, along with the setupstore.cgi script.

Then, flag the setupstore.cgi as executable: "chmod 755 setupstore.cgi". Your ftp client can do that too.

At last, execute the script in your browser, like:

http://www.mydomain.com/cgi-bin/setupstore.cgi

The script will untar the file, and flag all the directories and files correctly. If you untar the file yourself, or upload the shop with your FTP client, your script might fail, cause the directories/files would be owned by you, and not by the web server user. We welcome comments about the script, and how you fixed it to run on your platform, and we will integrate the changes in the next release.

Note that we assume no responsability of whether and how this script will work on your platform. There are systems where this does not work at all, therefore be forewarned!

Here is a link to the latest version of the setupstore.cgi.

 

10. Configure your merchant information, to accept credit card or check payments.

Once you checked all of the above, you might want to set up your system to accept credit cards with a payment gateway. The CITY Shop supports a multitude of payment gateways, and we included setup examples for each. If your bank is using a payment gateway not listed in our list, you can contact us and see maybe we can program the interface for you.

There are two types of merchant gateways: those that allow you to submit credit card information and receive the auth result over the same socket, and the others, like PayPal, WorldPay, etc.., which require to enter the card information on the gateway page form, and then return a response to the shop over a (hidden) post.

The following setup information needs to be edited in ShopSetup.pm:

For the first category, the "true" gateways, you will need to configure the $MerchantData according to the provided examples, please check our EPI page. You will also need the following key in the ShopSetup.pm:

-MERCHANT_DATA => $MerchantData,

VERY IMPORTANT! If your gateway specifies the use of -GATEWAY_CONNECT_METHOD, read on our EPI page about how to configure your system to support the remote connect method!

For the second category, we provided a merchant mapper hash in the ShopSetup.pm, with the settings for every gateway (older versions of the shop might not have this key, in which case you will need to add it right underneath the -MERCHANT_DATA). As you see in the example for "PayPal", the equivalent of the $MerchantData is being directly assigned to the key named as the gateway:

 -MERCHANT_DATA_MAP => {
  'CreditCard' => $MerchantData,
  'Check'      => $MerchantData,
  'PayPal'     => {
    -GATEWAY_NAME => 'PayPal', 
    -MERCHANT_ID => 'office@city.at',
#   -MERCHANT_LOGO_URL => "$SecureBaseURL/$ImagePath/storesmalllogo.gif",
    -EXTERNAL_METHOD => 1,
  },
...
},

For a complete documentation and examples of how to configure your $MerchantData information for the correct EPI implementation, please check our EPI page.

To disable the payment using a standard merchant gateway, you need to open ShopSetup.pm and comment out the following line:

# -MERCHANT_DATA => $MerchantData,

Same thing applies for external gateways, comment out the whole hash.

A documentation on the configuration of the payment gateway is on our EPI page.

 

Comments

Read the documentation.
Don't be afraid to ask.

Some things are not as simple as they seem. Your ISP might have his evil ways in plastering your way to success with things like SuExec, virtual machine hosting, aliasing of directories, and many other attempts at improving his control over the system, and decreasing your degree of understanding of what is going on. Some of these extras are good things to have, if they are installed properly, tested, and documented so, that you, me, or the guy around the corner could get the job done easily. When things are just not right, I have seen that quite often, moving to a different ISP is often cheaper than figuring out the maze...

Have fun :)