ShopSite TX 5.0 Installation Instructions
These instructions provide steps for installing and configuring the ShopSite TX software on the server that will host the stores. Instructions for installing the ShopSite TX screen pack on a Transact system are contained in the ShopSite TX 5.0 Screen Pack Installation Instructions. Once you have installed the software on both systems by following the instructions in both documents, your servers will be configured to offer merchants fast and powerful Web store creation coupled with industry-leading transaction processing and order tracking.
If you are upgrading from a previous version of ShopSite, please use the upgrading instructions.
Table of Contents
- I. Pre-Installation Considerations
- II. Planning ShopSite Directories
- III. Mall Initialization
- A. Edit the config_mall.aa File
- B. Run the start_install_mall_tx Script
- C. Register as Host Administrator
- D. Run the start_install_mall_tx Script (second time)
- E. Configure the Web server
- IV. Store Initialization
- A. Edit the config_store.aa File
- B. Run the start_install_store_tx Script
- C. Configure the Web Server
- D. Tell the Merchant that the Store is Ready
- V. Install Language Packs
- VI. Ongoing Responsibilities
- A. Roll Keys
- B. Request New Stores
- VII. Customizing ShopSite
ShopSite TX puts files in six directories:
- Executable files used by all stores are put in two separate directories, a SHOPSITE_DIRECTORY and a SHOPPING_CART_DIRECTORY. These directories need to be aliased in your server and accessible through URLs. The SHOPSITE_DIRECTORY must only be accessible by merchants. If you are using a Netscape server, see the information in the server configuration requirements about configuring Netscape to use .htacces files.
® Put these directories in or under your server's cgi-bin directory. As a security measure, you should configure your server to only serve CGI programs from the cgi-bin directories, not text files or HTML files.
- Security-related files are stored in the MALL_SECURITY_DIRECTORY. This directory contains passwords, and must be protected from inappropriate access.
® Put this directory in or under your server's cgi-bin directory.
- Graphics used by all ShopSite stores are stored in a separate directory that must be accessible by the Web server. The recommended directory is shopsite-images under your Web server's document root.
- Each store needs its own DATA_DIRECTORY to store its databases of products and pages.
® Put each store's DATA_DIRECTORY in the user space that you assign to the merchant, but make sure that it is not accessible from a browser. In other words, do not put the Data Directory under the Web server's document root directory.
- Each store also needs an HTML_DIRECTORY to store its HTML files, which are the generated pages for each store. This directory is sometimes called the store's output directory. The storefront URL must be aliased to the store's HTML_DIRECTORY.
® Put the HTML_DIRECTORY for each store in the user space that you assign to the merchant, or wherever your existing HTML goes.
Note that the images for each store are kept in a media subdirectory of the store's HTML_DIRECTORY, and you may want to allow each merchant FTP access to their own media directory.
These installation instructions refer to these directories and their associated URLs by their generic function, such as SHOPSITE_DIRECTORY, not by name. You, as the installer, must provide the actual names. Plan the directory locations before starting the installation. An example directory structure might look like this:
home
httpd
cgi-bin
ss = SHOPSITE_DIRECTORY
aliased to SHOPSITE_URL, such as
http://www.xyz.com/cgi-bin/ss
sc = SHOPPING_CART_DIRECTORY
aliased to SHOPPING_CART_URL, such as
http://www.xyz.com/cgi-bin/sc
ms = MALL_SECURITY_DIRECTORY
contains passwords; must be protected from inappropriate access
html
shopsite-images
Store1 = HTML_DIRECTORY aliased to Merchant 1's STORE_FRONT_URL
Store 1 pages
media Merchant 1 may need FTP access
Store 1 images
Store2 = HTML_DIRECTORY aliased to Merchant 2's STORE_FRONT_URL
Store 2 pages
media Merchant 2 may need FTP access
Store 2 images
data
Store1 = DATA_DIRECTORY
Store2 = DATA_DIRECTORY
You must edit one configuration file and run one shell script to prepare your server to host ShopSite TX stores. The script creates directories and installs software on the server. You must also register as a host administrator with the Transact system.
The config_mall.aa file contains settings used by the installation scripts to configure your mall and stores.
- Log in or su to the UNIX_WEB_USER_ID account.
- Change directory to the location of the install files.
- Open the config_mall.aa file with an editor and set values for the following variables. Do not enclose values in quotation marks. Note that there may be other variables in the file in sections indicating that they are for SC only; you can ignore those variables.
- SHOPSITE_DIRECTORY
- Absolute pathname of ShopSite directory; all CGI scripts for the merchants to manage and publish their stores reside here. The directory will be created if it does not exist.
- SHOPSITE_URL
- Absolute URL that references the SHOPSITE_DIRECTORY. This should point to a cgi-bin directory, such as http://host/whatever/cgi-bin/ss.
- SHOPPING_CART_DIRECTORY
- Absolute pathname of the shopping cart directory; CGI scripts for creating orders reside here. The directory will be created if it does not exist.
- SHOPPING_CART_URL
- Absolute URL that references SHOPPING_CART_DIRECTORY. This should point to a cgi-bin directory, such as http://host/whatever/cgi-bin/sc.
- SHOPSITE_IMAGE_DIR
- Absolute pathname of the directory for storing graphics used in the ShopSite merchant interface. The directory will be created if it does not exist.
- SHOPSITE_IMAGE_URL
- Absolute URL that references the SHOPSITE_IMAGE_DIR. This should be located under the Web server's document root, such as http://host/shopsite/shopsite-images.
- UNIX_WEB_USER_ID
- The Web server user ID.
- UNIX_WEB_GROUP_ID
- The Web server group ID.
- PATH_TO_PERL
- Absolute pathname to perl executable, for example, /usr/bin/perl.
- PATH_TO_TAR
- Absolute pathname to tar executable, for example, /bin/tar.
- PATH_TO_SENDMAIL
- Absolute pathname to the sendmail executable, for example, /usr/bin/sendmail.
- LOG_DEBUG
- Set to YES (all caps) to enable logging debug messages to a log file.
- DEBUG_LOG_DIRECTORY
- The full path name, with no file name, to where the log file is to be stored.
- DEBUG_LOG_FILE
- The log file name.
- BACKUP_ON_UPDATE
- If this is a new installation, enter NO. If you are updating an existing mall, enter YES to have the update script back up the existing ShopSite directories to tar files. The tar files can get large, so enter NO if your system does not have much available disk space.
Note: Tar on Solaris complains about symbolic links longer than 99 characters, and may not include those links in the tar file.
- TRANSACT_HOST_NAME
- Host or domain name of the Transact system, such as paydemo.openmarket.com.
- TRANSACT_HTTP_PORT
- The HTTP port number of the Transact system, typically 80.
- TRANSACT_SSL_PORT
- The SSL port number of the Transact system, typically 443.
- MALL_SECURITY_DIRECTORY
- Absolute pathname of the mall security directory, which is where key files and other associated files will reside. This directory is created if it does not exist.
- KEY_PASSWORD
- Password for the key database. The password must be 8-20 characters in length and contain at least one number or capital letter; all lowercase passwords will not be accepted. This is not necessarily the same password used with the host administrator account.
- HOST_ADMIN_EMAIL
- The e-mail address of the mall administrator (see C. Register as Host Administrator for more information). Be sure this is correct, as important messages relating to mall or store creation may be sent from time to time.
- HOST_ADMIN_USER_NAME
- The desired user name of the mall administrator account on the Transact system (see C. Register as Host Administrator for more information).
- HOST_ADMIN_PASSWORD
- The desired password for the mall administrator account on the Transact system (see C. Register as Host Administrator for more information).
You should only need to set the following variables once, though you can change them at any time.
- SCREEN_PACK
- Identifies the screen pack version to use. Should be set to ShopSite/v5.0.1.
- MINIMUM_USERNAME_LENGTH
- The minimum length for merchant user names. As a general rule, user names should be at least eight characters long.
- MAXIMUM_USERNAME_LENGTH
- The maximum length for merchant user names. 20 is a good number.
- MINIMUM_PASSWORD_LENGTH
- The minimum length for merchant passwords. As a general rule, you should not allow passwords of less than eight characters.
- MAXIMUM_PASSWORD_LENGTH
- The maximum length for merchant passwords. 20 is a good number.
- LOW_WATERMARK
- Number indicating a threshold. When the number of stores available to be assigned to new merchants falls below this threshold at the Transact system, the host administrator will be reminded by e-mail to request more stores. See Ongoing Responsibilities at the end of these instructions for more information on requesting stores.
- MONTHLY_KEY_ROLL_SCRIPT
- The file name of the key-rolling script to be generated by the start_install_mall_tx script. This file will be stored in the MALL_SECURITY_DIRECTORY.
- PROXY_SERVER
- (Optional) The server name of your proxy server.
- PROXY_PORT
- (Optional) The port number on the proxy server.
- Double-check the values that you set, and then save and close the file.
- Make a copy of the config_mall.aa file, as a security measure against the file being overwritten or erased.
The start_install_mall_tx script performs initial configuration of the ShopSite software on the server.
- Make sure that the UNIX_WEB_USER_ID and UNIX_WEB_GROUP_ID are set as "owner" and "group "of the SHOPSITE_DIRECTORY and SHOPPING_CART_DIRECTORY.
- Make sure that the UNIX_WEB_USER_ID can write to /tmp and can write to the directory that the install scripts are being run from.
- Log in or su to the UNIX_WEB_USER_ID account.
- Verify that your csp.id file is in the same directory as the start_install_mall_tx.ksh script.
- Run the script.
% start_install_mall_tx.ksh config_mall.aa 1
Note: |
All the scripts are designed to run under a KornShell (ksh). If your server does not have ksh installed, you may need to edit the scripts to run under a different shell. If you have problems running the scripts, try typing a "./" before the script name, for example, ./start_install_cgi instead of start_install_cgi.
|
- Check the log file for errors. If you left the LOG_DEBUG variable set to YES, then the install script created a log file in the DEBUG_LOG_DIRECTORY. The default name for the file is debug.log. Examine this file to ensure that there are no FAILED messages. If you find any of these messages, correct the problem (most likely a file permission problem) and rerun the script.
- When the install script has run successfully, note the instructions that it prints for registering as a host administrator. Section C (below) provides more details on this step.
You must register with the Transact system as the host administrator for your mall so that stores can be assigned to you and you can perform certain functions on behalf of the stores.
- Open a Web browser and go to the URL provided by the Transact administrator, which should have the following form:
http://transact_host_name/tms-ts/keymaster/register.cgi
- If your browser displays a login dialog box, click Cancel. You should then see the User name and Password page; select the option to register.
- Fill in all the information requested on the Create Host Administrator Account page. Set the locale to "en-US." Note that the Transact system checks e-mail addresses for uniqueness; you cannot use an e-mail address that is already registered with the system.
- Locate the file sok-file.txt in the MALL_SECURITY_DIRECTORY on the server. Open the file, and copy and paste the contents of the file into the "Certificate" section of the account creation page. Include the entire contents, from the line that reads
-----BEGIN PRIVACY-ENHANCED MESSAGE-----
up to and including the line that reads
-----END PRIVACY-ENHANCED MESSAGE-----
- Submit the registration.
- If there is any incomplete or invalid information, you will be directed to fix the information in the form. Otherwise, your host administrator account is created and you will be prompted to log in. Enter your user name and password to proceed.
Note: |
You must remember your host administrator user name and password for future use, but do not compromise your mall's security by writing it down where unauthorized people might find it.
|
- In the Keymaster Management Functions page, request some number of stores. (It is best to request 2-4 weeks worth of stores at a time.) You will be notified by e-mail when your request is granted and your stores are ready.
- Scroll down the page to the "Download Our Certificate" section. Click to download the Transact system certificate. Make absolutely certain to save it in the MALL_SECURITY_DIRECTORY with the file name keyscv-cert.txt.
- Wait until you receive an e-mail message telling you that your request for stores was granted. Do not proceed until stores have been allocated to your host administrator account.
When your request for stores is granted, you must run the start_install_mall_tx script a second time to finish configuring your server to work with the Transact system.
- Log in or su to the UNIX_WEB_USER_ID account.
- Run the script as follows:
% start_install_mall_tx.ksh config_mall.aa 2
where 2 indicates that you are running the script for the second time.
Configure the Web server to recognize the new directories:
- Alias the SHOPSITE_URL to point to the SHOPSITE_DIRECTORY.
- Alias the SHOPPING_CART_URL to point to the SHOPPING_CART_DIRECTORY.
The config_store.aa file and the start_install_store_tx.ksh script are provided as examples of how to call the underlying script that creates and initializes stores, which is install_store_tx.ksh. These scripts accept command line parameters, such as those passed by the start_install_store_tx.ksh script. You can customize the example script to suit your needs or create your own script. You may choose to configure your server such that, once a merchant requests a store by filling out an online form, the store will be created with no operator intervention required.
The start_install_store_tx script reads the settings in the config_store.aa file and creates the data and HTML directories for a new store and performs other configuration on the server. You can either edit the config file each time you need to create a store to set the values for that particular store, or configure the script to accept command-line variables. These instructions show you which variables to set.
- Open the config_store.aa file with an editor and set values for the following variables. Do not enclose values in quotation marks.
- SHOPSITE_STORE_ID
- A merchant user name, ideally 8-80 characters in length. This is the user name that the merchant uses to access ShopSite (the SHOPSITE_URL is password-protected).
- SHOPSITE_SELLER_PASSWORD
- The password associated with the SHOPSITE_STORE_ID. This should be 8-20 characters in length and containing at least one number. This is the password that the merchant uses to access ShopSite (the SHOPSITE_URL is password-protected).
- STORE_FRONT_URL
- Absolute URL of the merchant's storefront, that is, the store that is accessible to the merchant's customers via the Internet.
- SECURE_SHOPSITE_IMAGE_URL
- Specify the URL that ShopSite should use for images on secure pages, such as the order form. Usually this is the same as the SHOPSITE_IMAGE_URL, with the addition of https: instead of http:.
- SELLER_EMAIL
- The merchant's e-mail address. This must be correct, as the merchant is notified of orders and other important information via e-mail.
- DATA_DIRECTORY
- Absolute pathname to the data directory for the merchant's store. This directory will hold the product and pages database.
- HTML_DIRECTORY
- Absolute pathname to the HTML directory for the merchant's store. This directory will hold the generated HTML pages for the store.
- SELLER_USER_ID
- The UNIX user ID to be assigned to the store's HTML directory. You can assign each merchant a separate user ID, or use the same ID for all merchants.
- SELLER_GROUP_ID
- The UNIX group ID to be assigned to the store's HTML directory.
- PRODUCT_TYPE
- Enter the service level of the store: pro, mgr, lte, or exp.
- MERCHANT_LOCALE
- An identifier for the language and locale that the merchant will see. This must be one of the supported ShopSite locales defined in the localeinfo.dat file in the shopsite directory, such as en-US.
- BUYER_LOCALE
- An identifier for the locale and language that buyers will see in the store. This must be one of the supported ShopSite locales defined in the localeinfo.dat file in the shopsite directory, such as en-US. Do not enter a locale for which there is no language pack installed.
- STORE_CURRENCY
- The currency to use in the store. This value must be a three-character ISO 4217 currency code, as defined in the currency.dat file in the shopsite directory. You can find a list of ISO currency codes here.
- STORE_TYPE
- 0 = default
- PAGE_LIMIT
- The maximum number of pages allowed in this store. Leave blank for no limit.
- PRODUCT_LIMIT
- The maximum number of products allowed in this store. Leave blank for no limit.
- UPDATE_HTPASSWD
- Defaults to YES, which tells the install script to update the .htpasswd file. If set to NO, the install script will not update the file.
Note: ShopSite only sets up Apache-style passwords, using .htaccess files. If you are using a Netscape server, you can configure it to use .htaccess files by following the instructions at the Netscape site.
- TRANSACT_SELLER_ID
- Merchant user name on the Transact system. If left blank, then the SHOPSITE_STORE_ID is used, and the merchant has the same user name for both ShopSite and the Commerce Center. It is recommended that merchants have the same user name and password on both systems.
- TRANSACT_SELLER_PASSWORD
- Merchant password on the Transact system. If left blank, then the SHOPSITE_SELLER_PASSWORD is used, and the merchant has the same password for both ShopSite and the Commerce Center. It is recommended that merchants have the same user name and password on both systems.
- SHOPSITE_STORE_NAME
- The name of the store.
- SELLER_CHALLENGE
- A question that only the merchant should know the answer to, such as "What is your favorite flavor of ice cream?" This question will be used to verify the merchant identity before allowing certain actions, such as changing the password for the merchant account.
- SELLER_CHALLENGE_ANSWER
- The answer to the SELLER_CHALLENGE question.
- SELLER_PERSONAL_NAME
- The name of the merchant.
- SELLER_TAX_PLAN
- Set the type of tax the store will be charging:
- us - in the United States and charging sales tax
- no - in the United States and not charging sales tax
- vat - in a VAT country and charging VAT
- nov - in a VAT country and not charging VAT
- SELLER_ADDRESS1
- The first line of the merchant's mailing address.
- SELLER_ADDRESS2
- The second line of the merchant's mailing address, if required.
- SELLER_CITY
- The merchant's city.
- SELLER_STATE
- The merchant's state.
- SELLER_POST_CODE
- The merchant's zip or postal code.
- SELLER_COUNTRY
- The merchant's country.
- SELLER_PHONE
- The merchant's phone number.
- STORE_CUSTOMER_SERVICE_URL
- The full URL to the store's customer service page.
- STORE_CUSTOMER_SERVICE_EMAIL
- The e-mail address to reach customer service for the store.
- STORE_DECIMAL_SEPARATOR
- The character used to separate whole currency from fractional currency in prices; usually a period or a comma. (Enter the character; do not spell it out.) For countries that do not allow fractional currencies, such as Italy, enter "" (two double quotation marks with no space in between).
- STORE_PAYMENT_BRANDS
- A list of payment brands, separated by spaces. Valid values are:
- Discover: DI
- Master Card: MA
- Purchase Order: PO
- Visa: VI
- En Route: EN
- Diners Club: DC
- American Express: AM
- JCB: JC
- Demo Payment Brand: Demo
Note: If you list the "Demo" payment brand along with real payment brands, only the Demo brand will be functional, although the other brands will be listed on the order form.
- SHIPPING_1_NAME
- A name for the first shipping method available to customers. If left blank, this shipping method will not be configured.
- SHIPPING_1_BASEPRICE
- The base rate for shipping an order via the first shipping method. If this field is set to 0, only the SHIPPING_1_ADDPRICE is charged for shipping via this method.
- SHIPPING_1_ADDPRICE
- The amount to add to the SHIPPING_1_BASEPRICE for each unit of weight in the order. The formula for calculating shipping cost is: shipping_price = baseprice + addprice * (weight - 1). If this field is set to 0, only the SHIPPING_1_BASEPRICE is charged for shipping via this method.
- SHIPPING_2_NAME
- A name for the second shipping method available to customers. If left blank, this shipping method will not be configured.
- SHIPPING_2_BASEPRICE
- The base rate for shipping an order via the second shipping method. If this field is set to 0, only the SHIPPING_2_ADDPRICE is charged for shipping via this method.
- SHIPPING_2_ADDPRICE
- The amount to add to the SHIPPING_2_BASEPRICE for each unit of weight in the order. The formula for calculating shipping cost is: shipping_price = baseprice + addprice * (weight - 1). If this field is set to 0, only the SHIPPING_2_BASEPRICE is charged for shipping via this method.
- SHIPPING_3_NAME
- A name for the third shipping method available to customers. If left blank, this shipping method will not be configured.
- SHIPPING_3_BASEPRICE
- The base rate for shipping an order via the third shipping method. If this field is set to 0, only the SHIPPING_3_ADDPRICE is charged for shipping via this method.
- SHIPPING_3_ADDPRICE
- The amount to add to the SHIPPING_3_BASEPRICE for each unit of weight in the order. The formula for calculating shipping cost is: shipping_price = baseprice + addprice * (weight - 1). If this field is set to 0, only the SHIPPING_3_BASEPRICE is charged for shipping via this method.
- VAT_NUMBER
- The VAT registration number for the store or any text string you choose. The number or text you enter in this field appears in all VAT invoice and credit notes issued to customers. Leave this blank if the merchant does not want to display the VAT registration number.
- DEFAULT_VAT_COUNTRY
- A two-digit country code indicating the country in which the merchant will charge VAT.
- STORE_SERVICE_LEVEL
- Set to either gold or silver to set the features available to the merchant in the Commerce Center. Silver stores do order-capture only (no online payment processing), and they do not allow the merchant to administer customer or employee accounts.
- Double-check the values that you set, and then save and close the file.
- Make a copy of the config_store.aa file, as a security measure against the file being overwritten or erased.
- Log in or su to the UNIX_WEB_USER_ID account.
- Run the script, passing in the two configuration files as parameters:
% start_install_store_tx.ksh config_mall.aa config_store.aa
If you are running Linux, you may see an error message stating that the chown command does not support the -h option.
Make the following administrative changes to the Web server:
- Alias the STORE_FRONT_URL to the HTML_DIRECTORY for the store.
- Add the SHOPSITE_STORE_ID user name and the password SHOPSITE_MERCHANT_PASSWORD to the access list for the SHOPSITE_DIRECTORY.
Note: ShopSite only sets up Apache-style passwords, using .htaccess files. If you are using a Netscape server, you can configure it to use .htaccess files by following the instructions at the Netscape site.
You have completed initializing a new store. Now contact the merchant and give them:
- The URL they'll use for administering their store - it's the SHOPSITE_URL with /start.cgi appended.
- The SHOPSITE_STORE_ID (user name) and SHOPSITE_SELLER_PASSWORD (password) that they will need to log in to ShopSite.
(You do not need to perform this step if you will be hosting only English stores.)
To enable other languages besides English:
- Verify that you have successfully installed an English store by following the instructions in Section IV.
- Unzip or untar the language pack files into the directory that you run the ShopSite installation from.
- Install another store, and assign the new language to it.
Once you have a store installed with the new language, that language will appear in the drop-down list of languages in all other stores.
As the host administrator for the mall, you maintain the mall's security by creating new secret keys each month and uploading them from the ShopSite server to the Transact system. If the keys are not updated at least monthly, the Transact system will not accept orders from any of the stores in your mall. The process of creating new keys is called "rolling keys," and, fortunately, it can be automated by using cron to run a script that is provided in the kit.
The key_roll.monthly script is in the MALL_SECURITY_DIRECTORY. Edit the crontab file to run this script before the end of each month. Make sure that this script is not readable or executable by any users other than the host administrator account.
Important: |
You must run the key_roll.monthly script every time new stores are requested and granted by the Transact administrator. For example, if the host administrator requests 20 new stores and the Transact administrator grants the request, the 20 stores are now available, but they do not have any keys. Without keys, no orders can be placed at any of the new stores. The key_roll.monthly script creates new keys for all stores in the mall and gives the Transact system copies of the keys so that orders can be processed.
|
When the number of unassigned stores available for new merchants is running low (that is, below the "low-water mark"), the host administrator will be notified by e-mail. The host administrator should then go to the Transact Keymaster Management Functions screen (use a browser to go to the URL provided by the Transact administrator) and request new stores. The new stores are not necessarily automatically granted. Check that your new store request is being granted; do not assume that your job is done because you made the request. The start_install_store_tx script will not be able to proceed if there is not at least one store available.
You can customize parts of the interface that merchants and customers see as they interact with ShopSite. For more information, see the page on Customizing ShopSite.
