iHTML Merchant Installation on Unix

This document covers installation of the iHTML Merchant Professional and Enterprise version 2.x.

Before you Begin

The Merchant Store requires the following components to be installed and running before installation begins:

unixODBC

The iHTML Merchant requires the support for ODBC provided by a ODBC Driver manager to be installed prior to installation. The Driver Manager implements the ODBC standard for Open Database Connectivity, which is an interface the iHTML Merchant uses to communicate with any type of database.

Inline recommends that you install unixODBC for this purpose. This package is included with most recent releases of Linux distributions and FreeBSD, or alternatively you may find additional installation instructions at the unixODBC website - http://www.unixodbc.org.

Additional resources such as ODBC drivers and helpful links to ODBC resources may be found in the FreeODBC library, at http://library.freeodbc.org.

Database Server

The iHTML Merchant requires a database server to host a database for each store. A database server must be installed and running before installation may proceed.

Supported Databases:
MySQL - www.mysql.com
Postgres - www.postgresql.org
Oracle - www.oracle.com/database
Sybase Adaptive Server - www.sybase.com/products/databaseservers
Microsoft SQL Server - www.microsoft.com/sql

SQL scripts to create the database schema for a Merchant store are provided for the above database servers in the 'admin/scripts' directory. These scripts are intended to be used to create the store's database after the installation of a new Merchant store. The iHTML Merchant trial installation has automated this process for the MySQL server, and in the future a more advanced installation will be provided with support for other database servers. Thus installation is simplest for the MySQL database, and a manual installation of the store's database is required for other database servers.

ODBC Drivers

unixODBC drivers for most databases can be found at the FreeODBC library.
http://library.freeodbc.org

Merchant Installation will search for ODBC drivers in /usr/lib or /usr/local/lib. You can also specify an alternate location if you prefer.

* ODBC Support for Sybase and SQL Server databases is provided by the TDS driver.
* You will also need the Inline ODBC text driver named odbc-i01.so for the import and export functions of the Merchant. This is provided in the /usr/ihtml directory.

iHTML Merchant Installation

Please be sure you have the following information to provide the installation program, when prompted.

  1. If you are installing a trial version, you will need a 'key' provided when you downloaded the software.
  2. The destination path where the new store will be installed. The default directory is /usr/ihtml/htdocs/STORE_NAME
  3. The Username or UID that your web server daemon runs under. Normally this is the 'nobody' account.
  4. The path to your web server's document root, where HTML documents are stored.
  5. If you use the Apache Web Server, the path to the server's configuration files (the directory where httpd.conf and access.conf are stored).
  6. The path to your odbc.ini file included with unixODBC. Normally the path may be /etc/odbc.ini, or /usr/local/etc/odbc.ini, or /home/nobody/.odbc.ini.

I. Begin the Installation

The iHTML Merchant is distributed as a compressed file that's tar'd and gzip'd.

Step 1. Uncompress the installation files into the current directory.

Run,
>gunzip /path/merc2VVx.tar.gz
>tar xvf merc2VVx.tar
where VV is the minor version number and 'x' is a letter describing the edition.

Alternatively, the following command is available on some systems such as Linux and recent versions of Solaris:
>tar xvfz merc2VVx.tar.gz

Step 2. Run the 'newstore' script to create a new store. See Section II for help on using the newstore script. If you prefer to install a store manually, see Appendix A "Manually Installing A Merchant Store".

Step 3. Follow the Final Install Steps as described by the 'newstore' script. Restart your Web Server if need be, and continue installation on the admin site in 'Site - General Setup'.

The URL of your store will be:
http://www.domainname.com/storename/
  or
http://www.domainname.com/
if your store is installed to the document root of your website.

The admin section is at
http://www.domainname.com/storename/admin/
  or
http://www.domainname.com/admin/

II. The 'newstore' script

Run the 'newstore' script as many times as you like to install new stores on a single server.

The script will step you through a series of questions as the store is installed.

Note:

Step 1. Choose a Store ID. This should be a unique name for your store that doesn't include spaces, slashes, or % and ? characters. The ID is also used to suggest default path information for your store, such as the directory, web address, and database name.

Example: store1

Step 2. Store Path. Enter the destination directory path where you want the new merchant store files copied. The directory you select will determine the URL for your store.
To install the store to a URL such as http://www.domain.com/STORE_ID/, choose either the default of /usr/ihtml/htdocs/STORE_ID, or enter a path to a subdirectory of your web server's document root (eg. /usr/local/apache/htdocs/STORE_ID).
To install your store to a URL such as http://www.domain.com/, enter the path to your web server's document root. If your web server runs multiple virtual servers, this path should be the document root of the desired virtual server. The store's files will be copied to this directory.
Please note: The directory you enter should not contain any html files (especially index.html or home.ihtml).

Step 3. Path to the Web Server's document root. This is the root directory where the html files on your website are stored. Please enter this path so the install program can determine whether the store path you entered is aliased (or mapped) to your website.

Step 4. Which Web Server do you use. Enter an 'a' for Apache, 'n' for a Netscape web server, or 'o' for Other web server.

Step 5. The Username or UID that your web server runs as. Normally this is the 'nobody' account, but often system administrators choose a different account name.

Step 6. Setup determines if your store's files are within the web server's document root. If not, an alias must be made to map the directory to the document root.

If your web server is either Apache or Netscape, this can be done automatically by answering 'yes' to create the alias. If you prefer not to create an alias at this time or you don't think one is necessary, answer 'no'. Users of other web servers are reminded to create an alias manually; please see your web server's documentation for more instructions.

Step 6b. If you select Apache in step 4, setup will ask for the path to Apache's conf directory, where the httpd.conf and access.conf files are found. Some additional configuration lines will be appended to the top of both of these files, and a backup copy will be saved as access.conf.backup and httpd.conf.backup. Later, please move these configuration lines to the appropriate section of the .conf files if you prefer them to be organized.

Step 7. (Optional) Restrict access to the Merchant Store administration by IP address. If you selected Apache in step 4, setup can restrict access to the "admin" directory of your store by IP address, so that only the localhost, the machine's default subnet, and Inline's subnet (for technical support purposes) have access to the Merchant Store's administration pages. You may also be prompted for the path to Apache's .conf files.

If a Netscape or Other web server was selected, you are reminded to configure security authentication manually for the 'admin' directory of the new Merchant Store. Please see your web server's documentation for more instructions.

This is a recommended security precaution, to prevent visitors to your store from accessing the store's administration. You are also strongly encouraged to apply some form of password protection - please see your Web Server's documentation for instructions.

Step 8. Which database system will you be using? Please enter 'm' for MySQL or 'o' for Other.

Step 8b. MySQL:
a) You are prompted to create a database. Enter 'y' to begin to create a database now.
b) MySQL Privileged user name - Enter a mysql username which has access to create databases. On a default MySQL installation, press <enter> to select no user.
Example: root
c) MySQL user's password - Enter the password for the mysql user. If you did not enter a username in the previous step, press <enter> to select no password.
d) Store Database name - Enter a name for your store's database. Press <enter> to select the default name, which is your Store ID from Step 1. A database name must be a valid MySQL name, which contains only alpha-numeric characters (letters and numbers), the underscore, or the dollar sign, but no spaces.
e) Create a new mysql user. A MySQL user which has access to your database is needed by the Merchant Store to connect to your store's database. Enter 'y' to create a new user, or enter 'n' to enter an existing mysql username and password.
f) MySQL User Name. Enter a valid MySQL name, or press <enter> to select the default name (same as the Store ID).
g) MySQL users's password. Enter a password for the MySQL user.
h) If the MySQL server is an old version, you may be prompted to restart the MySQL server. Enter 'y' to restart MySQL, or 'n' to restart the server at a later time.
i) Populate the database with sample data from the O'reilly Book Store. Enter 'y' to populate your store's database with sample data.

Step 8c. Other Database Server: You are reminded to create a new database for your store. Please see Appendix A for details and refer to your Database Server's manual for specific instructions.

Step 9. Create an ODBC datasource. An ODBC datasource is needed by the Merchant Store to access the store's database.

Step 9b. If you selected MySQL in step 8, setup will ask if you wish to create one. Enter 'y' to create one now.
a) Path to your ODBC .ini file. Enter the path to your ODBC Driver Manager's INI file. Normally this is /etc/odbc.ini, or /etc/local/odbc.ini
b) Setup will search for an existing database driver on your system. If one is found, you are asked to confirm the file path. Select 'n' to enter a different path. If a driver is not found, you are asked to enter the path to an existing ODBC driver for your database.
c) Setup will search for an existing ODBC Text driver on your system. If one is found, you are asked to confirm the file path. Select 'n' to enter a different path. If a driver is not found, you are asked to enter the path to an existing ODBC Text driver.
d) Two config sections are appended to the top of the ODBC .INI file. A backup will be saved to odbc.ini.backup.

Step 9c. If setup does not create a datasource for you, you must do this manually after setup completes. Please see Appendix A for instructions.

Step 10. Final Install Steps.

The installation completes with a reminder to manually complete any incomplete steps. Reminders appear, for example, if you answered "no" to any of the questions or you selected a database server other than MySQL. You must complete these steps before proceeding with the final installation steps.

a) Following setup, you may need to restart your Apache Web Server daemon, to recognize any changes to its configuration files.

b) Visit the URL http://www.domainname.com/storename/admin/resetinc.ihtml to initialize store defaults.

c) Visit the URL http://www.domainname.com/storename/admin/, and complete your store setup on the General Setup page. The necessary settings to configure are the Site and Cookie paths, your address information, and email address.

Your store installation is complete.


Appendix A : Manually installing a Merchant Store

Copy the Merchant files to the Web Document Root

a) Copy the merchant files to a directory within your Web Server's document root, an aliased directory, or within a virtual server's document root.
b) Change ownership of the destination directory to the username that the Web Server runs under. The Web Server user must have read and write access to the Merchant store directories and files.

Restrict access to the store's administration pages

It is a recommended security precaution to secure web access to the "admin" directory of your Merchant Store. Please see your web server's documentation to learn how to apply password protection and IP address restrictions to a directory of your website.

Create the Merchant Store's database

On most database systems, this involves creating a database, running SQL scripts to create the database schema and insert data, and creating a database user which has access to insert/delete/select/update/drop/create objects in the store's database. SQL scripts are provided for supported database servers in the admin/scripts/ subdirectory of your store.

admin/scripts/[dbmode] :
merctables.[dbmode] - creates the database schema
mercdata.[dbmode] - inserts default store values that are required
mercsampledata.[dbmode] - inserts the O'reilly Sample Store data

[dbmode] = the database server used to host your store.
eg. mysql, postgres, sql (for sqlserver), sybase, oracle

Register an ODBC Datasource

Locate the odbc.ini file that your ODBC Driver Manager uses, and append following two config sections to the file.

# Here is a sample entry for a Postgres database:
[store1]
Database = store1_DB
Driver = /usr/lib/libpsqlodbc.so
DSN = store1
HOST = 127.0.0.1
PORT = 5432
#Server = localhost # May be needed
#Servername = localhost # May be needed
#Driver = /usr/lib/libmyodbc.so # Driver name for MySQL
#Port = 3306 # MySQL Port

# Import/Export DSN for Merchant Stores
[store1imex]
Driver = /usr/ihtml/drivers/odbc-i01.so
Path = /path/store1/
DefaultDir = /path/store1/
Sep = ,

* See the next section on updating the datasource.inc file.

Update the datasource.inc file

After creating an ODBC Datasource by hand, update the admin/datasource.inc file within your store's directory.
1. Enter the ODBC Datasource name you registered in the previous step as the value of "dbname".
  eg. <iEQ NAME="datasource" VALUE="store1">
2. Enter the "username/password" of your database user as the value of "loginname".
  eg. <iEQ NAME="loginname" VALUE="mercuser/mercpass">
3. (Merchant Enterprise Only) Enter the "storeid" value for your store.
  eg. <iEQ NAME="storeid" VALUE="1">

Final Installation Steps

a) Run the admin/resetinc.ihtml file within your store.
eg. visit the URL http://www.domainname.com/storename/admin/resetinc.ihtml
b) Continue setup on the 'Site - General Setup' page of your store's admin section.
eg. visit the URL http://www.domainname.com/storename/admin/, and click Site, then click General Setup.
c) Enter the correct values for the Site and Secure URL's and Cookie paths. These URL's should end with a forward slash. Enter your contact information, and any other settings, then click save to apply your changes.
d) Visit your store online!