ShopSite

ShopSite TX 4.2
Content Server Installation Instructions


These instructions provide steps for installing and configuring the ShopSite TX software on a content server, which is 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 4.2 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.

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. Upgrading
V. 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
VI. Ongoing Responsibilities
A. Roll Keys
B. Request New Stores
VII. Customizing ShopSite

  1. Pre-Installation Considerations
  2. Planning ShopSite Directories
  3. ShopSite TX puts files in six directories:

    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

  4. Mall Initialization
  5. You must edit one configuration file and run one shell script to prepare your content server to host ShopSite TX stores. The script creates directories and installs software on the server. You must also use a Web browser to register as a host administrator with the Transact system.

    1. Edit the config_mall.aa File
    2. The config_mall.aa file contains settings used by the installation scripts to configure your mall and stores.

      1. Change directory to the location of the install files.

      2. 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 used to create 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.

        MALL_LOCALE
        (This variables has been deleted in version 4.2.1)
        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.

        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 host administrator. 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 user name of the host administrator account on the Transact system.

        HOST_ADMIN_PASSWORD
        The password for the host administrator account on the Transact system.

        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/v4.2.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.

      3. Double-check the values that you set, and then save and close the file.
      4. Make a copy of the config_mall.aa file, as a security measure against the file being overwritten or erased.

    3. Run the start_install_mall_tx Script
    4. The start_install_mall_tx script performs initial configuration of the ShopSite software on the content server.

      1. 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.

      2. Log in or su to the UNIX_WEB_USER_ID account.

      3. Verify that your csp.id file is in the same directory as the start_install_mall_tx.ksh script.

      4. Run the script.

        % start_install_mall_tx.ksh config_mall.aa 1 1

    5. Register as Host Administrator
    6. 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.

      1. 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

      2. Do not enter a user name or password (as you don't have one yet). Click the Cancel button. When you see the User name and Password page, select the option to register.

      3. Fill in all the information requested on the Create Host Administrator Account page. 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.

      4. Locate the file sok-file.txt in the MALL_SECURITY_DIRECTORY on the content 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-----
      5. Submit the registration.

      6. 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.

      7. 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.

      8. 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.

      9. 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.

    7. Run the start_install_mall_tx Script (second time)
    8. When your request for stores is granted, you must run the start_install_mall_tx script a second time to finish configuring your content server to work with the Transact system.

      1. Log in or su to the UNIX_WEB_USER_ID account.

      2. Run the script as follows:

        % start_install_mall_tx.ksh config_mall.aa 2 1

        where 2 indicates that you are running the script for the second time.

    9. Configure the Web Server
    10. 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.

    11. Upgrading
    12. Follow the steps below to upgrade your mall from a previous version of ShopSite TX to version 4.2:

      1. Change ownership and permissions (optional). To install versions of ShopSite TX prior to version 4.1, you had to be logged in to the root account. That is no longer true, however, you must either run the upgrade as root, or change ownership and permission on all ShopSite files and directories to the UNIX_WEB_USER_ID. We recommend that you run the upgrade from the root account if you originally installed ShopSite from the root account.

      2. Edit the config_mall.aa file, per the instructions in section III.A. It is strongly recommended that you set BACKUP_ON_UPDATE to YES to have the upgrade script tar up all ShopSite-related directories. Should something go wrong, you can untar the files to return to the previous version. The BACKUP_ON_UPDATE option can use quite a bit of disk space, so make sure you have enough before upgrading. The amount of disk space required depends on the number and size of stores in your mall.

        Note: Tar on Solaris complains about symbolic links longer than 99 characters, and may not include those links in the tar files.

      3. Update your mall with the following command:

        % start_update_mall_tx.ksh config_mall.aa

        Note that the upgrade process takes 20 seconds to upgrade each store on the Transact side, or about 180 stores per hour. That is in addition to the time required to upgrade all mall-wide files.

    13. Store Initialization
    14. 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.

      1. Edit the config_store.aa File
      2. 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 content 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.

        1. 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.

          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
          (This variable is new in version 4.2.1.)
          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.

          STORE_LOCALE (only in version 4.2)
          BUYER_LOCALE (new in version 4.2.1)
          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.

          STORE_TYPE
          0 = pay once

          PAGE_LIMIT
          The maximum number of pages that merchants can create.

          PRODUCT_LIMIT
          The maximum number of products that merchants can create.

          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.

          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?"

          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_LANGUAGE
          The default language for the store.

          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.)

          STORE_PAYMENT_BRANDS
          A list of payment brands, separated by spaces, such as VI MA.

          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.

        2. Double-check the values that you set, and then save and close the file.

        3. Make a copy of the config_store.aa file, as a security measure against the file being overwritten or erased.

      3. Run the start_install_store_tx Script
        1. Log in or su to the UNIX_WEB_USER_ID account.

        2. Run the script, passing in the two configuration files as parameters:

          % start_install_store_tx.ksh config_mall.aa config_store.aa 1

          Depending on the version and configuration of Linux on your server, you may see an error message stating that the chown command does not support the -h option. You can ignore the message, as it does not affect ShopSite installation or operation.

      4. Configure the Web server
      5. Make the following administrative changes to the Web server:

        1. Alias the STORE_FRONT_URL to the HTML_DIRECTORY for the store.

        2. 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.

      6. Tell the Merchant that the Store is Ready
      7. 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.

    15. Ongoing Responsibilities
      1. Roll Keys
      2. 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 content 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.

      3. Request New Stores
      4. 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.

    16. Customizing ShopSite
    17. 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.


    Footnotes

    1 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.