System Administrator's Guide Zelerate: AllCommerce
Installing Manually
Installing manually means installing step by step from a command line instead of running a script. You can install AllCommerce manually if you cannot run configure.pl or choose this method to install and configure AllCommerce. This section walks you through the various steps of installing and configuring AllCommerce, creating a database, and setting up a virtual host for your Web server, and discusses how to handle the various configurations and data loads that are needed for AllCommerce. The checks performed and steps are almost the same as an automated installation.

Attention!
Make sure that you are in the os_allcommerce directory when you use command line arguments.

Instead of configure.pl
If you had problems installing AllCommerce using configure.pl, you can start from the first manual step and begin the installation process again or you can move forward to the step where configure.pl ran into difficulties.

Checking for Dependencies
AllCommerce has several prerequisites that need to be installed in order for the system to work properly. Please make sure that the prerequisites are installed and working properly.
If you have not installed all the prerequisites that are needed for AllCommerce, we strongly advise that you install them before continuing on with the installation procedure.

Database Tables
AllCommerce uses a database table to store information that will be accessed by the ecommerce application. The information stored in the database table is a centralized point for all data within your site.
You can either create a new database or use an existing database table. We strongly recommend that you choose to create a new database table for use with AllCommerce.

Manually Create New Database Table
This step will walk you through the creation of a new database table, for use with AllCommerce.

To create a new database table go to a command prompt and type:
                mysqladmin create {new database name}
            
Manually Integrate with Existing Database Table
To integrate with an existing table, follow the steps below.
From a command prompt type:
                mysqldump -t mysql {existing database table} > data/{existing database table}.mysqld
            
This will save all data from the existing table you wish to use with AllCommerce. A copy of this data is stored in a file named {existing database table}.mysqld located in the data directory of AllCommerce.
                mysqladmin drop {existing database table}
            
You will then see the following warning message:
                Dropping the database is potentially a very bad thing to do. 
                Any data stored in the database will be destroyed.  
                Do you really want to drop the '{existing database table}' 
                database [y/N]
            

Warning!
Please be sure you really are prepared to drop this data. Answering 'y' to this step means that all data stored in this database table will be lost.

Manually Setting up the AllCommerce Data Structure
AllCommerce requires that your database table be configured with a set of data structures specific to AllCommerce.
To import the AllCommerce data structure into the database table you created, type the following from a command line:
  • For MySQL
  •          mysql {name of database table} < conf/tables.mysql.skel
             
  • For PostgreSQL:
  •          PostgreSQL  {name of database table} < conf/tables.postgresql.skel
             
  • For Oracle:
  •          You must use the script configure.pl for Oracle.
             

Manually Configuring the Web Server
AllCommerce requires that you have a Web server installed and working properly.
At this time AllCommerce is optimized to only run with the Apache Web server. However, there is a ported version of the AllCommerce available which runs under the Microsoft IIS server.

Apache Virtual Host
The Apache Web server will need to have several changes to the default configuration in order to work properly with AllCommerce. The Apache Web server configuration file which you need to edit is named httpd.conf. This file is located in the server root for Apache in a directory named conf.
For example, on a default installation of Apache, the server root will be either /etc/httpd or /usr/local/httpd.

Attention! Zelerate recommends that you create an Apache virtual host for the site you wish to use with AllCommerce.

Sample Virtual Host Entry
Here's a sample virtual host entry for a typical AllCommerce installation:
                
                   ServerAdmin Webmaster@host.some_domain.com
                   DocumentRoot /home/httpd/os_allcommerce/
                   ServerName host.some_domain.com
                   DirectoryIndex index.html index.shtml index.htm index.cgi
                   ErrorLog logs/host.some_domain.com-error_log
                   TransferLog logs/host.some_domain.com-access_log

                   AddHandler cgi-script .cgi
                   AddType text/html .shtml
                   AddHandler server-parsed .shtml

                   ScriptAlias /cgi-bin/ /home/httpd/os_allcommerce/cgi-bin/

                   # allow access to the site
                   
                      AllowOverride all
                      Options Includes FollowSymlinks ExecCGI
                      Allow from all
                   

                   # disallow access to everything else
                   
                      Options None
                      Order deny,allow
                      deny from all
                   

                
            

Making Apache Work with AllCommerce
There are several important elements that need to be configured for Apache to work properly with AllCommerce.

DirectoryIndex
AllCommerce uses index.cgi as the directory index. You must make sure index.cgi is specified in the list for DirectoryIndex.
                DirectoryIndex index.html index.shtml index.htm index.cgi
            
Directory Permissions
You will need to turn on some directory permissions in order for Apache to execute cgi scripts and follow symbolic links. These options are enabled using the Directory tag.
                 
            
ExecCGI and FollowSymlinks
The initial script, index.cgi, that welcomes users to your site and redirects them to the appropriate language and interface tree is a cgi script. Therefore, in order for the Web server to execute this script in the os_allcommerce directory you must give permissions to the Web server to execute cgi scripts.
AllCommerce uses symbolic links in the creation of its file names. You must allow the Web Server to follow symbolic links in the os_allcommerce directory.
The ExecCGI and FollowSymlinks options should be placed in the Options tag within the Directory brackets.
                Options Includes FollowSymlinks ExecCGI
            
ServerName
This setting must match the combination of siteserver and sitedomain in the AllCommerce configuration file machine.conf. This will be the server and domain name you are configuring to run with AllCommerce.

Attention!
ServerName is the most common problem users have when configuring Apache to work with AllCommerce. If you do not have these parameters set correctly you will experience a login loop problem when trying to use the AllCommerce administrator. This problem is caused because the Web server is unable to set a proper cookie.
Here is an example of a proper configuration for AllCommerce and Apache ServerName.
                ServerName	www.mysite.com
            
AllCommerce machine.conf:
                # The site domain name for the server you have OS AllCommerce installed.
                # For example: '.mydomain.com'
           
                sitedomain      .mysite.com 
           
                # The server name for your site.
                # For example: 'www'
           
                siteserver      www
            
You will need to restart your Web server after editing Apache httpd.conf for your changes to take effect.

Warning!
Users of openmerchant0.7.pre6 and earlier versions should note that the site configuration file store.pm has been changed to site.pm, which is now a machine-generated file. Some variables within have also had name changes. It is therefore (strongly) recommended that you do not attempt to reuse any existing store.pm files you may have and upgrade to this version of AllCommerce.

Manually Load AllCommerce Initial Data
You will have to load an initial data load into AllCommerce which contains default behaviors for this application.
To import the AllCommerce initial data load, from a command line: Change directory to the os_allcommerce directory and run:
                ./configure.pl idl
            

Manually Load Shipping Methods and Rates
AllCommerce uses real-time shipping methods in checkout. The shipping carriers supported in this release are: UPS, Fed Ex and USPS.
The script import_shipping_tables.pl allows you to use the download information from United Parcel Service (UPS), U.S. Postal Service (USPS), and Federal Express (FedEx) to calculate shipping costs for a customer transaction. By using information that you download from the shippers you want to use, import_shipping_tables.pl translates this files into SQL insert statements that can be imported into your database.

Weight Information
In order to charge shipping for an item, you must have weight information for each item being sold. This information should be placed in the database at the time of the creation of the object in the AllCommerce Administrator. Failure to provide weight information could result in incorrect shipping calculations.

Restrictions
import_shipping_tables.pl is designed for U.S. domestic service only. International shipping involves a greater set of problems (e.g., import taxes, currency, import restrictions).

Information Needed For import_shipping_tables.pl
Shipping tables are normally constructed based on the distance ("zone"), along with the type of service (e.g., "overnight") and weight ("rate"). In practical terms, two sets of tables are needed from each shipping company.
import_shipping_tables.pl is designed to take information from UPS, USPS, and FedEx Websites in order to construct the required shipping tables that will be put into the database.
  • For UPS:
    1. Go to www.ups.com/using/software/currentrates/rates_in_us.html.
    2. On the UPS Website, for zone information input the first three digits of the "Origin Postal Code" (i.e., where you will be shipping from) and press the download button.
    3. You will be prompted to download a file that is named by the three digit zip, suffixed with the extension .csv (e.g., 944.csv). This is your zone information, specific to your shipping location.
    4. After getting the zone information, download the "Download All Rate Charts" via ZIP format.
  • For USPS:
    1. Go to postcalc.usps.gov/Zonecharts. Enter the first three digits of the origin postal code, and press the "Get Zone Chart" button. You will need to save this Web page.
    2. Use the "Save as" button from the browser to save the file "default.asp".
    3. For the rate chart, download the Express Mail and Priority Mail files (em.txt and pm.txt) from www.framed.usps.com/consumer/csv.htm (note that the extension is .com, rather than .gov).
  • For FedEx:
    1. Go to www.fedex.com/us/rates/zonelocator. Enter the 5-digit ZIP code and click on the "search by zip" button.
    2. You will then be prompted to download a PDF-formatted file. Download the file.
    3. Open the PDF format with your PDF viewer (e.g., Adobe Acroread (TM)).
    4. Click on the text button on the view and cut and paste the first table containing the continental US information (zipcodes and zones only - do not cut and paste header info) to a file called fedexfile1.txt.
    5. Cut and paste the other PDF table (containing Alaska and Hawaii ZIP codes and zones) to a file called fedexfile2.txt (remember to cut and paste only the ZIP codes and zones - no header info is needed).
    6. Download the rates by service ASCII file at www.fedex.com/us/rates/downloads/.
Using import_shipping_tables.pl
If you are using all three shipping companies, then you should have the appropriate files for UPS, USPS and FedEx.
See www.Zelerate.org for updates to this section.

In the tools directory, create a directory called "data", if it is not already there. Place the files you will be using into the data directory. For .tar.gz, uncompress and untar the file and unzip the .zip files, as well.
In the tools directory, run import_shipping_tables.pl, which should convert the files above into SQL insert statements for import into your database. The SQL insert statements are grouped into files per the shipping method and either zone or rate (e.g., UPS.rate.dbid or UPS.994.zone.dbid).
Once these files are created, you will need to load them into your database. They will then be available as shipping options during customer checkout.

Successful Manual Installation
After manual installation has been successfully completed, you should be able to proceed to login to the AllCommerce admin screen and start creating your site.
                https://sitename.sitedomain/cgi-bin/om/admin/login.cgi
             
                username: admin
                password: allcommerce
            
For more information on how to use the AllCommerce managers to build your site, see the Zelerate AllCommerce User's Guide.

Loading YOUR Data
AllCommerce provides a Content and an Inventory Manager to load data into the system.

Importing Existing Data
At this time, there is no tool in this AllCommerce release to load existing data. For more information on the AllCommerce data structure see Data Structures.

Loading Images
AllCommerce stores images in the filesystem in the os_allcommerce/images directory. On most systems this directory can be mounted which allows for a drag and drop interface. If you are running AllCommerce on a single server, images can be transferred through your systems secure copy function.
As items are created using the AllCommerce Content manager, unique object identifiers are assigned. These unique identifiers should be used in naming the assets in the images directory.

Tax Tables
There are no tax tables used in this release of AllCommerce. The tax information is handled in the configuration file site.conf.

General System Security
AllCommerce is fully capable of taking advantage of the secure encryption schemes offered by secure Web servers.
You can offer secure online ordering and processing of data by utilizing an SSL-enabled Web server such as IBM httpd or Stronghold.

Blowfish
AllCommerce utilizes the Blowfish algorithm for password, gift certificate, and other internal data encryption. This 64-bit, variable-length key designed by Bruce Schneier is gaining wide acceptance as a very strong encryption algorithm. It is unlicensed and freely available.
For more information on Blowfish visit: www.counterpane.com/blowfish.html

Prev
Installing Automatically with a Script
Up Next
Troubleshooting Your Installation
All Commerce User's Guide Table of Contents