OpenCart 0.93 -- 7/15/2005 Installation Instructions Note that there are plans to improve the installation proceedure when release 1.0 is completed. In the meantime, these notes should help most people install the system and get it up and running. The good news is that the system is actually very easy to install and configure. If you have no programming experience whatsoever, you may need a little help from someone that is familiar with programming basic Perl code. This is especially true for configuring shipping costs in checkout.pl, and in customizing the confirmation page in confirm.pl. We plan to add functionality to the system in the near futre that will allow all of the tweaks necessary to run the system to be done from a single system configuration page. See the TODO file for more info on planned future enhancements. There are several active sites running OpenCart at the present time. One of these sites, US Fireworks, generates a considerable amount of revenue through OpenCart. If you are interested in seeing a site that uses the application in production, go to http://www.usfireworks.biz/ . Development Environment This software is being developed in a UNIX environment using FreeBSD 5.4, the Apache 1.3 web server, MySQL 4.0, and Perl 5.8.6 (as well as 5.6.1). It should be able to run in Windows environment (or any other) with a few small tweaks, like changing the first line of every script to point to the location of your Perl interpreter. This is a standard Perl web application, so if your system can support Perl 5, you can probably get this to work on your system. Getting Started Before you begin to configure OpenCart on your server, there are a few pieces of software that you will need to get started. This is a list of the things you need: 1) You will need a copy of MySQL 4.0. You are welcome to try MySQL 4.1, however you should not that the format for TIMESTAMP elements now defaults to display format, instead of internal format YYYYMMDDHHMMSS. While we do not anticipate any problems in the software, we won't know that is fully compatible until we actually test it here. MySQL is availabe for both UNIX and Windows. You will want to install both the client and server modules. If you run your server on the same system and your web server, you can limit the server to IP address 127.0.0.1 in order to prevent external access to the database from the Internet. Only the web server needs access to the database server. You can get MySQL from the following site (free): http://www.mysql.com/ It is recommended that you install MySQL on your server before you proceed with the Perl modules, as some of the Perl modules may require access to the database server in order to test and verify the install of those modules. 2) A Perl interpreter, version 5.4 or later. It may work with earlier versions of Perl, but OpenCart has no experience with anything earlier than version 5.4. We recommend version 5.6.1 or 5.8.6. If you do not have Perl on your system, you can get it from the CPAN archive at http://www.cpan.org/ for UNIX, or from http://www.activestate.com/ for Windows (its free). 3) You will need several Perl modules in order to support the database, and to provide encryption services for cookies and the like. These are the modules you will need: * Bundle::DBI * Bundle::DBD::mysql * Crypt::CBC * Crypt::Blowfish * Crypt::SSLeay * Digest::MD5 * Net::SSLeay For UNIX, these modules can be found on CPAN and installed as follows: perl -MCPAN -e 'install Bundle::DBI' If you are using the Active State distribution of Perl, you will need to use the Active State perl package manager, ppm, to install these modules. If you have trouble locating these modules on the Active State site, do a Google search for +ppm and the package name. All of the above modules are very common, so you should have no trouble finding them. A good site for people getting started with Perl on windows is http://www.northbound-train.com/perlwin32.html . 4) You will need a web server. As everything we develop uses the Apache web server, we recommend using Apache. However, any web server that is capable of running CGI scripts should be capable of running the OpenCart application. You can get a copy of the Apache web server (free) from the Apache website: http://www.apache.org/ OpenCart will run under Apache version 1.3 or 2.0 without problems. In addition to installing and configuring Apache (or some other web server) to run on your server, you will need to configure a website for your store. The OpenCart software does not require any special configuration options on your web server -- it is a straight CGI-based application. All you really need is a directory for your CGI scripts, and a directory for your web pages. We also recommend that you have separate directories for your server log files and the database schema and scripts, but this is completely optional. If you are using the Apache server with a VirtualHost configuration for your website, we recommend you setup separate directories for your CGI scripts, your database tools, and your HTML root directory. Here is a sample VirtualHost configuration we use here for the OpenCart application: ServerName www.opencart.org ServerAdmin dgs@accelix.com DocumentRoot /usr/local/www/virtual/opencart/data ScriptAlias /cgi-bin/ /usr/local/www/virtual/opencart/cgi-bin/ CustomLog /usr/local/www/virtual/opencart/logs/access.log combined ErrorLog /usr/local/www/virtual/opencart/logs/error.log Options FollowSymLinks AllowOverride None order allow,deny allow from all Options All AllowOverride All Order allow,deny Allow from all In the configuration above, we have a home directory defined as /usr/local/www/virtual/open . In this directory, we have the following subdirectories: cgi-bin -- contains all CGI scripts data -- contains the HTML root directory for the website db -- contains the database schema and utilities logs -- contains the web server log files Of course, you are welcome to set this up any way you prefer. But this type of organization makes it simple to organize the site and maintain files. Installing OpenCart We assume at this point that you have a working version of Perl with the necessary modules, a working MySQL database server, and a working web server with a configured website for your application. 1) Unpack the distribution. OpenCart is distributed as a standard UNIX gzip'ed tar file. To unpack the distribution on a UNIX server, use the following command: tar xvzf opencart-0.93.tgz If you are using Windows, the WinZip utility can be used to unpack the distribution. The system will create a directory called opencart, with three subdirectories -- cgi-bin, data, and db. 2) If you did not unpack the files in the place where you are going to use them, copy the files in the cgi-bin directory into the CGI directory for your website, and copy the files in the data directory, including any subdirectories, into the HTML document root directory. 3) Fix the path to Perl in each of the CGI scripts. This is done by changing to the cgi-bin directory and editing each of the files that end with ".pl". The default is "#!/usr/bin/perl". On UNIX systems, you can find the path to Perl using the command "which perl". If you are installing the software in a Windows environment, you will need to specify the drive as well as the path to Perl, for example "#!c:\perl\bin\perl.exe". 4) Make sure all of the scripts in the cgi-bin directory are marked as executable. In UNIX, this is done with "chmod 755 *.pl". 5) In order to customize the shopping cart for your application, all you need to do is change a few values in the cart.pm module. Windows users will want to use an editor like TextPad, or an editor that can edit UNIX text files. These are the values you may want to change in the cart.pm module: $https -- If this is set to 1, then the OpenCart application will try to switch to the secure SSL when the customer attempts to check out. If you do not support SSL for your website, make sure this item is set to 0 (but you SHOULD support SSL if you want to keep your customers). You can get a free SSL certificate from http://www.cacert.org/ . $lookup -- Set this to 1 if you want to use the database to lookup prices and other data for items. As we are still in the process of developing an interface to support this function, we recommend you leave this set to 0 until the interface becomes available. Set to 0, the system will act and function just like PayPal. $expdays -- Controls the number of days a cookie for a shopping cart will remain valid. Three days is good if you want people to recover their orders after they leave your site. You can set this to 0 if you don't want persistent shopping carts. $scriptchk -- This is a check that is enabled to eliminate cross-site scritping problems. If it is set to 1, any scripts that are entered maliciously into your shopping cart will be removed. It is recommended that this be set to 1. $secret -- This is the MD5 hash secret and is used in encrypting cookie data. It should be a random string of 16 upper and lowercase letters, numbers, and symbols. It is used to increase the complexity of the cypher. The default value is "changeme". $cryptkey -- This is the encryption key used to encrypt the cookie that is used for the shopping cart. Like the $secret item, it should be at least 16 characters long and composed of random letters, numbers, and symbols. The default value is "changeme". $admin -- This is the address that email will be sent to when a purchase is made. You want to set this to be a valid email address for receiving orders from your web store. Be sure to escape the '@' in the email address with a backslash '\', or Perl will complain loudly. $errto -- This is the email address to use for receiving error reports from the system. This should be the email address of the person that is responsible for maintaing the website and its database. Be sure to escape the '@' in the email address with a backslash '\', or Perl will complain loudly. $sendmail -- This is the path to your email program. The program you use should behave similar to sendmail. If you are running Windows, you can get programs that function like sendmail (or similar) from these sites: http://www.indigostar.com/sendmail.htm http://www.glob.com.au/sendmail/ http://www.blat.net/ http://www.geocities.com/SiliconValley/Park/8312/mail.htm Note that Windows users may have to tweak the routines that rely on sendmail to get them to work with a different utility. This should be relatively straight forward to do. $$db1{name} -- This is the name of your MySQL database. The value that exists here should be ok. $$db1{host} -- This is the name of the server that is running your MySQL database. If your database server is running on your web server, you can leave this set to "localhost". $$db1{user} -- This is the userid that will be used to access the database from the shopping cart application. Remember this value as you will need it when we create the database in a subsequent step. The default is "cart", but feel free to change this to your own value. $$db1{pass} -- This is the password that you will use with your userid exists here sh uld bepplication to access the database. Remember this value as you will need it when we create the database in a subsequent step. The default is "buyme", but you should change this to be some other value, preferrably eight or more characters long with mixed case letters and digits. At this point, you have essentially configured the shopping cart for your application. All you need now is a database. 6) Configure the Authorize.Net payment process. This is done by editing the payment.pl program. OpenCart uses Authorize.Net to handle its merchant gateway processing for credit card charges. In order to have this work, you need a credit card merchant account and an Authorize.Net account. Accelix LLC can arrange to get you a merchant account if you do not have once already. They can also sign you up for Authorize.Net gateway service for your existing merchant account. Once you have a merchant account and and Authorize.Net account, you are ready to configure the payment program. The program payment.pl has several fields that need to be changed to get your payment process working. These are the fields you need to modify: $login -- This is the userid that Authorize.Net has issued for you to pass transactions through their gateway. $passwd -- This is the password that Authorize.Net has assigned for you to pass transactions through their gateway. $storename -- This is the name of your organizations, which will show up on the customer's credit card bill. $testmode -- This is value that determine whether the gateway is operating in test mode or in production mode. If the value is set to "TRUE", then the gateway is functioning in test mode and no actual financial activity will take place. If the value of this item is "FALSE", then the system is live and credit cards that are processed through the system will be charged. The system comes with the application configured in test mode. Simply uncomment the $testmode = "FALSE" line, and add a comment (#) in front of the line that says $testmode = "TRUE". $admin -- This is an email address that is used to receive orders that are sent by the system. Be sure to escape the '@' in the email address with a backslash '\', or Perl will complain loudly. $smfrom -- This is the from address that will be used when the user is sent invoices for their purchase. This should be a real address in case the user wants to correspond with your store. Be sure to escape the '@' in the email address with a backslash '\', or Perl will complain loudly. 7) Configure the Authorize.Net retail site to recognize the correct field delimiters for the OpenCart application. Authorize.Net, as provided "out of the box", is not configured correctly to handle SSL transaction format. You need to make the following changes in the merchant interface so Authorize.Net will understand your requests: a. Login to Authorize.Net merchant interface and invoke the system configuration panels. b. For the type of system, choose "ADC Direct Response" using the version 3.1 format. c. In the Direct Response section, set the default field delimiter to an & by entering the value in the open box to the right of the list of delimiters. Set the list item to blank (you will have to scroll up in the list to do this -- its obscured). Finally, set the "Delimited Response" value to YES. d. After you have tested the interface to Authorize.Net, you will need to turn off "Test Mode" through the Authorize.Net interface. All Authorize.Net accounts are set to "Test Mode" by default when they are initially configured by Authorize.Net. Once your account has "Test Mode" turned off, you will be able to collect money from credit card transactions. This should be all you need to do to have Authorize.Net work properly with the shopping cart. Note that if you don't have an Authorize.Net account at the time you are installing OpenCart, you can proceed with the rest of the installation. All of the OpenCart functionality will work fine, with the exception of the credit card transaction component. This is remedied as soon as you have an account on Authorize.Net. If you do not have an Authorize.Net account, or a merchant account, download and print the file "AUTHORIZE-NET.pdf" (in Acrobat PDF format) supplied with this software. Fill out the application and FAX or mail the application to the address provided inside the document. It generally takes two to three days to obtain a new merchant account, and only a day or so to obtain an Authorize.Net account if you already have a merchant account. 8) Configure shipping and sale tax modules. The calculation of shipping charges and state sales tax is performed in the checkout.pl CGI routine. In order to add sales tax, simply assign a percentage to your state using the tax hash. For example, the state of Pennsylvania is configured in the checkout.pl program with a 6 percent tax -- this is done on line 68 of the program where the statement says: $tax{PA} = .06; You can replace this with another state, delete this line entirely, or add multiple states. For example, to add state sales tax for Maryland (MD) and Virginia (VA), the following lines could be added to the table: $tax{MD} = .05; $tax{VA} = .06; This shows Maryland with a five percent tax, and Virginia with a six percent tax. If there is not sales tax value for a specific state, no sales tax is calculated. In most cases, you only need to charge sales tax in the states where your business physically resides. To tailor shipping charges for your store, look for the routine named "CalcShipping", starting on line 468 of the program. This routine is custom coded to handle your own shipping costs -- you will need some Perl programming experience to make this modification. The amount in $nettotal is the total cost of the order without shipping or sales tax. You can use this value to compute a shipping cost based on order cost. You can also read through the %shipto hash to determine shipping costs. The important thing for this routine to do is to return the amount of the shipping cost to the calling routine. The method of calculating those costs is up to you. Future versions of OpenCart will constrain this in a database table and eliminate the need to make program changes for calculating shipping costs. 9) Modify confirmation instructions in confirm.pl and payment.pl. This is one area that OpenCart shines -- customer confirmation. Many merchants get ripped off every year by people that purchase goods over the Internet, and then reverse the charges on their credit card. If you have written terms that a customer must agree to before submitting an order, you will be in a better position to dispute those chargebacks when they occur. The terms and conditions of the order are defined starting at line 232 in the confirm.pl module. To see a more extensive version where this feature is being used, look at the shopping cart feature at US Fireworks at http://www.usfireworks.biz/ -- they require the customer to certify a variety of things before they place an order. This confirmation feature allowed US Fireworks to avoid over $25,000 in chargebacks in one year alone. The terms and conditions are repeated again in the payment.pl module in two places -- the email confirmation invoice sent to the customer, and the online invoice confirmation page displayed after the order is accepted. You will find the email confirmation terms on line 580 of payment.pl, and the online confirmation terms on line 893. Note that confirm.pl and payment.pl use a Perl feature called "here documents" to generate the HTML and text for the confirmation messages. You should be able to modify these areas accordingly without having to tangle with specific program code. Also note that if you add an email address to the message, be sure to escape the '@' in the address with a backslash '\' in order to escape the symbol from being interpreted as an array -- otherwise, Perl will complain. Note that anytime you change a Perl program, you can verify that it is syntactly correct by running "perl -c program.pl" where "program.pl" is the name of the program you are checking. Perl will either tell you the module is "Ok", or it will list line numbers where it finds errors. In future versions of OpenCart, we are going to isolate these sections of text and HTML in database tables so they can be changed without having to modify a program. 10) Establish the OpenCart application database. To start, change to the db subdirectory where you extracted the OpenCart distribution. a. Edit the contents of the create-user.sql script and make sure that the database name, userid, and password correspond with the values you chose when you were editing the cart.pm module. There are comments in the script to help you identify the elements you need to modify. b. Create the database userid for the OpenCart application. This is done by reading the create-user.sql script with the mysql utility as follows: mysql -u root < create-user.sql Depending on your mysql configuration, you may need to modify the mysql command to add additional parameters, such as the -h host paramater, or the -p paramater for password prompting. This may be required in the other steps that follow as well. c. The first time through, you will need to create an empty database before you can process the schema for the application. To do this, enter the following command: mysqladmin -u root create cartdb If you choose a database name that is different than cartdb in cart.pm, use the name you choose instead of cartdb when defining the initial database above. d. Now it is time to define the tables in your database by processing your database schema through the mysql interpreter. The database schema is defined in a file named cart.dbd in the db subdirectory. If you changed the name of the OpenCart database in cart.pm when you were customizing the CGI scripts earlier, you will need to edit cart.dbd and change the database references from "cartdb" to what ever you selected for a database name. The statements in the schema file that are affected by a name change include: drop database cartdb; create database cartdb; use cartdb; To create the database and its tables, run the mysql utility and use the cart.dbd file for input, for example: mysql -u root < cart.dbd You now have a working database for the OpenCart application. You should be able to test the OpenCart application to verify the software is working and communicating with the database. Testing OpenCart There is a web page called "testcart.htm" that can be found in the data subdirectory in the distribution. By invoking this webpage, you should be able to see how OpenCart works, and validate a successful install. The testcart.htm page has several examples of how to use OpenCart as a shopping cart. You should be able to look at the source code for this page and determine how the items in the cart are setup. The PayPal User's Manual can also be helpful if you are using the webscr module as the interface for your store. Installation Assistance If you are having a difficult time installing OpenCart on your server, we are available to help you with the configuration and installation of the software at standard consulting rates. In most cases, it takes less than two hours to do everything. If you get stuck, call us. Dave Stoddard Accelix LLC http://www.accelix.com/ 240-235-6597 : office dgs@accelix.com