Server Codex

SERVER CODEX

Software, Hardware, Tutorials, News and Reviews

osCommerce Installation on Mac OS X

Pre-requisite reading: Installing phpMyAdmin, Useful Apache Tweaks

Prior to the arrival of Mac OS X, there weren’t many e-commerce software applications available for people to wanted to build and host an online shop on the Mac platform. With the arrival of an operating system that supports Apache, PHP, and MySQL, however, would-be Mac shopkeepers now have all the tools they need to configure and operate their very own web-based e-commerce storefront.

While there are currently a number of commercial and open source e-commerce solutions, osCommerce in particular stands out for its vibrant community support and low cost (free). The steps below explain in detail how to install osCommerce on Mac OS X, after which you can browse the included demo catalog, add/remove products, and configure other aspects of the store from with the provided web-based Admin interface. This article is the first in a series about e-commerce on Mac servers and will be followed by additional articles with more information about building your own online business.

As always, no previous knowledge is assumed other than the required reading listed above, so please post a message in the Forums if you think there’s an aspect of the tutorial that would benefit from clearer explanation.

Installation

  1. Download the latest Milestone Release of osCommerce. You can download one of the daily snapshots, but this isn’t recommended since most community-developed contributions are designed to work with specific Milestones.
  2. Expand the downloaded archive with OpenUp or your preferred application. Open the folder entitled oscommerce-2.2xxx (where xxx is the current milestone release). Inside are a number of files and folders, but for the moment we are only interested in the catalog folder. Move the catalog folder to /Library/WebServer/Documents/. (Your mileage may vary should you decide to use the /Users/username/Sites/ folder instead.)Inside the catalog folder is another entitled install. At this point, if you were to follow the instructions provided in the osCommerce distribution and load the installation URL, you would probably see the following error:

    “FATAL ERROR: register_globals is disabled in php.ini, please enable it!”

    While you can enable register_globals via php.ini as suggested, a better method is to enable it only for the specific applications that need it. This is done by creating an .htaccess file. While Apache normally defaults to disallowing .htaccess overrides, a quick change to Apache’s configuration file (httpd.conf) will allow us to make folder-specific overrides. Since you’ve already performed that step as part of the required reading above, we’ll forge ahead and enable register_globals via the .htaccess file.

  3. osCommerce already comes with its own .htaccess file, which we’re going to modify in order to turn the register_globals setting on. Assuming you have already moved the osCommerce catalog folder to the /Library/WebServer/Documents/ as directed above, switch to the Terminal, copy and paste the following command, and hit return:open -e /Library/WebServer/Documents/catalog/.htaccess

    This command will open up the .htaccess file with TextEdit. At the end of the file you will find the following commented-out block:

    #<IfModule mod_php4.c>
    # php_value session.use_trans_sid 0
    # php_value register_globals 1
    #</IfModule>

    Uncomment three of these lines by removing the # signs so that the block looks like the one below, and then save and close the document window:

    <IfModule mod_php4.c>
    # php_value session.use_trans_sid 0
    php_value register_globals 1
    </IfModule>

  4. Now that register_globals has been enabled for our osCommerce catalog, it’s time to run the installation script. If you are testing this on a live server with a domain name, load the following URL in your browser:http://www.yourdomain.com/catalog/install/install.php

    If you are simply performing a test installation on a local machine without a domain name, load the following URL in your browser:

    http://localhost/catalog/install/install.php

    If when loading one of the above URLs you still get an error about register_globals being disabled, chances are good that [a] the Apache httpd.conf override step was not performed properly (did you remember to restart Personal Web Sharing afterward?) or [b] the above changes to the .htaccess file in the catalog folder were not made correctly.

  5. You should now see the osCommerce New Install screen. Leave the two marked checkboxes alone and click on the Continue button at lower right. On the next screen, enter the following into the Database Import fields:Database Server: localhost
    Username: [enter the MySQL control username]
    Password: [enter the MySQL control password]
    Database name: [osCommerce and catalog are common names, but anything will do.]
    Persistent connections: [Leave it unchecked, unless you have your own dedicated server.]
    Session storage: [Choose Database, unless you have your own dedicated server. In that case, choose Files.]

    Once all the fields have been entered and you’ve double-checked them for accuracy, click on the Continue button. A test connection is made at this point, and assuming it is successful, the next screen will begin with:

    “A test connection made to the database was successful.”

    Click on the Continue button to import the database.

  6. Assuming there were no problems, you should see confirmation that the database import was successful. To make sure the new database was created successfully, open a new browser window, log out of phpMyAdmin if you’re logged in, log back in, and you should see “catalog” listed in the “Databases” pop-up at upper left. The (46) you see next to catalog indicates how many tables are in the catalog database. Switch back to the osCommerce installation window, and click Continue.
  7. You should now see the osCommerce Configuration screen. Assuming osCommerce was able to successfully guess the appropriate paths, you should see four pre-completed text fields followed by a checkbox. These five settings should be:WWW Address:
    http://www.yourdomain.com/catalog/ or http://localhost/catalog/

    Webserver Root Directory:
    /Library/WebServer/Documents/catalog/

    HTTP Cookie Domain:
    yourdomain.com or localhost

    HTTP Cookie Path:
    /catalog/

    Enable SSL Connections: [Leave this unchecked, unless you have an SSL certificate installed on your server.]

    Click on the Continue button, after which a confirmation screen will appear. Look over the configuration settings and make sure that everything is entered correctly. Click on Continue again, after which you should be informed that an error has occurred.

  8. The above error is not surprising, since we haven’t set the correct permissions for two important files. Copy and paste the following six lines into the Terminal, hitting return after each one:cd /Library/WebServer/Documents/catalog/includes/
    touch configure.php
    chmod 706 configure.php
    cd /Library/WebServer/Documents/catalog/admin/includes/
    touch configure.php
    chmod 706 configure.php
  9. Going back to the web browser, click on “Retry” to ask osCommerce to check the permissions of the respective configure.php files. This time there should be no errors, and you will instead see all the configuration values that are about to be set. Check them one last time, and then click on the Continue button at lower right. You should then get a message that says, “The configuration was successful!”
  10. Before you begin playing around with the catalog and the admin interface, there’s one last bit of clean-up to do. First, go to the /Library/WebServer/Documents/catalog folder and drag the install folder to the trash. Then copy and paste the following lines in the Terminal:chmod 644 /Library/WebServer/Documents/catalog/includes/configure.php
    chmod 644 /Library/WebServer/Documents/catalog/admin/includes/configure.php

    You are now ready to begin setting up your e-commerce store. Going back to the web browser, you’ll see links to the Catalog and the Administration Tool. It be may useful to bookmark these for future reference.

    http://localhost/catalog/default.php
    http://localhost/catalog/admin/default.php

Congratulations! osCommerce is now installed. The osCommerce system is designed to facilitate extensive configuration of your store from within the Admin interface. This includes configuration of payment modules, shipping modules, multiple languages/currencies, and many other options.

That said, it is important to understand that there are many aspects of the osCommerce system — including both functionality and appearance — that can only be customized via modification of the PHP code itself. If you don’t need to customize OSC’s look/features, or if you are well versed in PHP, this won’t be a problem. Otherwise, it may be worthwhile to get some professional assistance.

Further reading:

osCommerce Wiki
osCommerce Forums

Leave a Comment