February 27, 2008

How to install Sunshop

I've been meaning to write up how to install Sunshop, my favorite shopping cart, which is made by TurnkeyWebTools (see Sunshop). I'll be interspersing many of TWT's own instructions so that you'll have some references if you're looking through the \docs\sunshop_install.txt file. Installation is pretty much the same for both Sunshop 3.5.1 and Sunshop 4, and shouldn't take long … writing this article took much longer than installation.

Here's part of the new Sunshop 4 admin panel, so you can see that it's not just a bunch of strangely-named and categorized links. Pretty elegant and speedy — things that are likely to impress you or your clients.

Sunshop 4

Why it's my favorite: Sunshop has a huge pile of features and the TWT guys have been fantastic at implementing new features requested by their customers — meaning, among other things, that Sunshop 4 is search engine friendly out of the box. The entire checkout is secure. As well (another of my requests), while you can edit the templates through the admin panel, you can also edit the templates on your computer and just upload. This, to me, is true love, as I hate clicking through admin panels to edit code (and I always have a backup on my computer just in case). Or how about customers who want to know the shipping fees when they're in the View Cart area and haven't carried through to the point where they'll find out — Sunshop recently wrote a little module (included in the purchase price) that does just that.

Lastly, I have to say that, although free open-source shopping carts are available, I'm happy to pay in order to get something that works solidly and to have an incredibly nice company stand behind its products — and to lend a hand if necessary.

You can also view the Sunshop product tour and demo at the turnkeywebtools.com site.

Sunshop installation in brief …

Essentially, you'll gather some information, download Sunshop, edit the config.php file to add your database information, upload the files to your web hosting account, and run the installation program. Done right, this is a breeze. I've included additional information (and much of Sunshop's install information) below for clarity and assistance, but even though this page is lengthy, that's pretty much it.

All that said, what you do with your Sunshop install and your website is under your control, so these instructions are provided without warranty, blah blah. One recommendation: back up everything. Always. And often.

What you'll need

  1. A copy of Sunshop (get the .zip version); I'll go into that below but you'll need to purchase it beforehand — and, when you do, you'll be asked to assign it to a domain and will get an "account" at turnkeywebtools.com with a username and password. Note these down, as you'll need them for the install.
  2. A program to "unzip" files — since the Sunshop files are compressed into one large file, you'll need to uncompress ("unzip") them; my favorite is WinZip.
  3. A text editor to make changes to the "config.php" file.
    Do NOT use a word processing program (like Microsoft Word); if you're on a Windows computer, you can use NotePad. I prefer NoteTab (there's a freeware version, although I use NoteTab Pro).
  4. A web server or web hosting account with PHP and MySQL (database) support. You'll also need all your login information, including the FTP login information for the next item on this list.
  5. An FTP program (a File Transfer program) to upload the files to your web hosting account or server. Set it up before you start the installation. FTP programs: WS_FTP or CuteFTP
  6. A web browser to run the installation — Internet Explorer, Firefox, Opera or Safari will do.

Get your database info (or set up your database)

To set up Sunshop, you'll need your MySQL database hostname, username, password and database name.
If your web hosting company has already set up a database for you, they've likely provided that information.

If you are or will be running multiple applications from one database (whether the database is already set up or not), be sure to add a prefix in your Sunshop config.php (covered below) — so that the Sunshop part of the database is separate from the other stuff. Very important. Did I mention backups?

If the database is not yet set up, here are a couple of methods of doing so:

If your web hosting account has cPanel:

  1. Log into cPanel > MySQL® Databases
  2. Create a database by giving a name to your new database and click "Create Database"
  3. Create a user (fill in username and password) and click "Create User"
  4. Add Users To Your Databases: select a user and a database, then click "Add User to Database"
  5. Write down all of the above, as you'll need it soon.

To set up the database via SSH (Secure Shell Access), see my Setting up the MySQL Database.

TIP: this "empty" database, the database after Sunshop inserts "tables" into it, and a text file containing the full current database information (or "mysqldump") are all called "the database". I mention this because it can be confusing unless you know.

Download Sunshop

Log in to your Turnkey Web Tools account and select the Sunshop format and version of your choice.
TWT recommends that you download the latest version available. The distribution and format you choose should depend on what's running on your server (web hosting account) and your computer.

Note: make sure that your domain name in your TWT client account is correct, as Sunshop will verify it during the install; if it's wrong, the installation won't … install.

Which Distribution? SunShop encrypts a few key files, so choose the one that best suits your needs:

  • Zend version (I recommend this if Zend is running on your server)
  • SGuardian version (seems to be gone for Sunshop 4)
  • Ioncube version (for which you'll need to upload the Ioncube files to your web hosting account)

If you don't know what's running on the server, go to TWT's Quick Install Guide, download the Version Checker and follow TWT's instructions.

Note: when you're done, delete the get_version.php file from your server; no need to alert others to what's running on your server.

Which Format? Since the Sunshop files are compressed into one large file, you'll need to un-compress it, so choose the version that corresponds to the un-compressing program on your computer. I recommend the .zip format.

(Alternatively, you can download the tar.gz (tar), which TWT recommends for Unix/Linux users for extraction
on the web server itself. If you know how to do that, you likely don't need this writeup, so I'll skip it.)

Download the Sunshop file to your computer where you can find it again (say, on the desktop).

Unzip the Sunshop Files (Unpacking)

Next, uncompress (unpack) the Sunshop files. If on Windows, you may use
WinZip, WinRar or any other extraction software.

For WinZip:

  1. Double-click the .zip file, which will be named something like sunshop_4_1_0_zend.zip, depending on the distribution and format you chose. WinZip will display all the files in its window. Now, you could drag/drop all the files to a new folder — but Sunshop is not a bunch of files all in one folder, so:
  2. Very important: click the Extract button, which will cause WinZip to (a) put the files into a new folder (b) sorted into the correct folders.

Winzip - Extract

Edit config.php

Now you'll edit the generic config.php
file with your own database information. Locate the config.php in the "sunshop/include/" folder. Open it in a text editor (not a word processor) and you'll see the code below. Although I've added the "databasepassword" so that you can see it, it's blank in the config.php file. You may not need to change "localhost".

<?PHP
// Hostname Or IP Of Server
$servername = "localhost";

// Name of Database
$dbname = "sunshop40";

// Username And Password To Log Into Database
$dbusername = "root";
$dbpassword = "databasepassword";

// Table Prefixes: Do not change the value after the install has been finished!
// $dbprefix = "ss_"; // Uncomment this line if this is a new install.

// Persistent Connection To Database
// $usepconnect = 1;
?>

Detail from TWT's instructions (and a note or two from me):

$servername: Usually you are fine leaving this at "localhost" but if the actual MySQL database is located on a different server you will need to change this to the proper hostname or IP address.

$dbusername: Set this to the username you created or were assigned.

$dbpassword: Set this to your assigned or created password.

$dbname: Set this to the name of the database you created or were assigned.

$dbprefix: By default this is commented out (see the "//" in front of it) and not used. It's good to use a prefix if you're going to run different applications from the same database (e.g., Sunshop and a blog): just uncomment this line by removing the "//" before the line.

Upload your Sunshop Files to your web hosting account

Connect your FTP program to your web hosting account, select the Sunshop folder on your computer and upload it to your server. (Per TWT: There is no need to do it file by file, and doing so may alter the paths and directory structures. Or, if you are installing locally on your own computer, just place the files into the proper directory.)

NOTE: the following files must be uploaded in binary format (if, when you run the install, it bombs out along the way, this is very often the problem; just upload them again in binary format):

/install/
/admin/libsecure.php
/libsecure.php

Note: the slashes — as in: /word/ — indicate a directory (or "folder" in Windows parlance).

Set Permissions

"Set permissions" means to specify what is allowed in specific areas of your server/web hosting account … like here, where you want to add product images via the Sunshop admin panel — you need to tell the server to allow Sunshop to upload those images. That's setting permissions, otherwise known as or "CHMOD" (change mode).

CHMOD 777 (set permissions to 777) these directories (folders):

  • admin/backup/
  • admin/reports/
  • catalog/
  • images/products/

How to set permissions in WS_FTP:

  • With WS_FTP, connect to the server
  • Right-click the file or folder for which you want to change permissions
  • Select "Properties"
  • Check the two empty boxes (see image below) and click "Okay"
    The Numeric Value should change to "777".

WS_FTP permissions

Install Sunshop

You've uploaded the files but they're actually just sitting there on the server. Now you'll need to run the install part of the Sunshop program. There are several steps to the Sunshop installation; most of this is from TWT's install instructions, with my notes:

Start the Installation

Using your web browser, go to the install/directory on your server:

Example: http://www.yoursite.com/sunshop/install/

Step 1: Confirm Installation and Accept License Agreement

Read the license agreement and agree in order to continue. If you are unable to see a "submit" button at this point, try re-uploading the install file.

Step 2: License Key

Per TWT: this will ensure that you have the proper license key file and will check the integrity of the license. If any of the checks fail, you will not be able to continue with the install. If the domain name does not pass, you most likely entered the wrong domain into your account at turnkeywebtools.com when you generated your key. If this occurs, contact TurnkeyWebTools so they can reset the key in your client
account.

NOTE: at first glance, this page looks like it's requesting your username/password AND the license key — but it won't accept them. I'll highlight the pertinent words:

"Please either enter in your login details for the Turnkey Web Tools site along with the domain name associated with your license OR login to your account and copy the license pasting it into the area below marked for the license key."

I usually use the domain and username/password for turnkeywebtools.com; the install will validate them and move you along to the next step.

Step 3: Configuration Check

This step will make sure you have the appropriate settings in the config.php file
and that it's on the server/web hosting account. If the settings are not correct, edit the config.php
in the admin directory before you attempt to continue. You may have to click your browser's back button to go to the previous page, and then continue from there.

Step 4: Configuration Check

Sunshop will attempt to connect to the database using the config.php Depending on your settings, you may get different results at this point. Again, TWT's install information and my notes:

"Connection Complete!"
This means the connection has been made; you may proceed.

"You have specified a non existent database. Trying to create one now…"
If the database you specified needs to be created it will attempt to do so. If it is unable to create the database you will need to make sure you have the permissions to do so. (See my section above on creating the database.)

"Warning: Access denied for user: "user@localhost' (Using password: Yes)"
The warning may vary but this means that the username or password in the config.php are incorrect. This can also mean that you do not have access to (permission to use) the database.

"Connection Complete!
The database already exists."

You can choose to continue by selecting "Continue To Next Step" or "Continue To Next Step And Reset Tables".

The points here are that (a) you may already be using the database for something else, like a blog, or (b) you may wish to do so in the future. So:

– if you select the first option, it is a good idea to define a value for the "$dbprefix" in the "config.php" so that you do not overwrite any current data in the database (that is, data from another application).

– If you select the second option, the tables needed will be erased and recreated. DO NOT select reset if you have data you need in the database you defined in your "config.php" file.

Note: since I already created the database, I get the "Database already exists" warning — and, since I'm not going to be using this database for other application and it's empty, I select "Continue" without resetting the tables. Don't select the reset option if you already have data in the database.

"Can't connect to local MySQL server through socket…"
If you get the above error, make sure that MySQL is running on your server. If you believe it, is make sure you have the proper location to the mysql.sock defined in your my.conf file. (That is, call your web host.)

If you get any other error message and need assistance, contact TurnkeyWebTools. They're great at helping out with installations.

Step 5: Creating Tables

At this point you should see only one message: "Tables set up successfully". If so, continue to the next step.

If you get a message similar to "There seems to be a slight problem with the database…", view the source of the page to get the exact error message. You will find the error at the very bottom of the page. You may need to go back and select reset in order to continue.

Step 6: Add Administrator

Choose a username, password and email address for the primary account user. Don't make them obvious, and don't forget to write them down!

Step 7: Setup Successful

Congratulations: you have successfully installed Sunshop. At this point be sure to DELETE the /install directory (Sunshop will prompt you to do so if you haven't already done it).

If you receive an error at this point, there was an error sending the email to verify your installation. You don't need to take any immediate action as the install was success but you will need to edit the mail settings in the general settings area.

Set a password on your Sunshop /admin directory

Yes, you'll already need to log in to your Sunshop admin panel. However, because hackers often try to log in (and because data in a shopping cart is pretty sensitive stuff), I prefer not to leave the login page out there where they can run programs to try to log in. Instead, I block access entirely by setting a password on the directory. Yes, this means you'll have to log in twice (once to the admin directory and once to the Sunshop admin panel), but it's a good security measure. Yes, I do this with blogs, too.

You can do this fairly easily with cPanel; just plunk around in the "Password Protect Directories" section of cPanel.

Shop Settings

Next, log into your Sunshop admin panel. I would highly recommend that you always log in using the secure URL to your site, which will be something like this (notice the https, which is the secure URL):

https://site.com/store/admin/login.php

Go to Manage Settings > Company Info — just fill it out with the pertinent information, and get started with your store.

Sunshop Settings

 

Okay, that's it — the end of this Sunshop installation article. I hope this is of use to you. I'll likely be writing a Sunshop 4 review, as they've fixed everything I wanted and included a whole lot more. And perhaps some small articles about how to modify templates.

16 Comments to "How to install Sunshop"

  1. Canadian Fine Arts says:

    It is a useful article for those who would like to install shopping carts on their websites.

  2. Diane Vigil says:

    Thanks, Canadian. I was hoping it would be of help.

  3. David says:

    You mentioned in your very useful install guide:

    "Or how about customers who want to know the shipping fees when they're in the View Cart area and haven't carried through to the point where they'll find out — Sunshop recently wrote a little module (included in the purchase price) that does just that."

    I use Sunshop and have not come across this module yet, which would be extremely useful. Can you let me know where I can find it?

  4. Diane Vigil says:

    Hi David, and thanks.

    Are you using Sunshop 4? The plugin is in one of the later versions of SS4 (it was released after the initial Sunshop 4), although I'm not sure which one. If you've got it, it's in:

    Settings > Manage Plugins > Available Plugins

    Have a look there. If you don't see it, you may have to upgrade SS4. Sunshop 4.1.0 has a number of plugins.

  5. David says:

    Thanks for the response Diane. I am currently using the latest version of Sunshop (4.1.0) but I still don't seem to find the plugin that you mention, unless I'm completely overlooking it.

    Here is the available list of plugins that I have available:

    Control Scan (PCI Compliance)
    iDevAffiliate
    PayPal Express Checkout
    Post Affiliate Pro
    preCharge (Fraud Screening)
    Sale Items
    Shipping Estimator (Realtime Shipping)

    If it's one of the above, please let me know because I'm quite interested in making this available on my website.

    Thanks,
    David

  6. Diane Vigil says:

    Ah. It's the Shipping Estimator, although it does need to be used with realtime shipping. Just enable that one and try it out.

  7. Drew says:

    Great instructions, I was super frustrated on an early step because I was entering my user/passwd and the license key. Thanks for the heads up, I should\\\'ve read a little more closely.

  8. Diane Vigil says:

    Yes, that's one of the issues with the install. I've made the same mistake myself, which is why I highlighted it. :)

  9. Jay says:

    I use Sunshop and have not come across this module yet, which would be extremely useful. Can you let me know where I can find it?

  10. Karl says:

    Hey,

    How do I change the name of the pages on the homepage and reorder them? (like remove gift registry and have an about us page?)

    Cheers

  11. Diane Vigil says:

    Hi, Jay. These sound like good questions for Turnkey Web Tools' forums … just search the forums for information: http://forum.turnkeywebtools.com/

  12. Andrew says:

    Thank you so much for the great tutorial! Im having trouble installing ioncube. Any tips?

  13. Diane Vigil says:

    It's been ages since I've installed it (most sites we work on have Zend, which I prefer). As I recall, it was just a matter of uploading it in a separate folder just off root.

    Since you didn't mention what trouble you're having, perhaps this will help (with particular mention of php.ini): http://www.webhostgear.com/77.html

    This assumes you have shell access. Otherwise, perhaps your host can help?

  14. Sunshop Shopping Cart Review says:

    […] is a breeze — edit the config file, upload the files and run the web-based install. (My How to install Sunshop post was written for people who are less familiar with installing web […]

  15. Leonard says:

    what I would like is a listing of all functions and their associated variables for sunshop. since this information does not appear anywhere on their site. It would really be helpful to know what variables are being called for shipping tables or for realtime shipping so I can make modifications within the shop. but I can't get any information from turnkey about it. I think the software itself is really good but I have to admit the support operations at turnkey leave me more then a bit cold. and I hate the fact that their system generates automatic rate our support forms every time I submit a ticket or answer their questions. I have been in communications with them steadily for 3 months and still don't have an operational store. correction: stores. because one is for international and the other is for local US customers. so in as much as I like the software I can't get it to do what we want consistently and have no choice but to look elsewhere.
    thanks for your pointers I'm well past that point though and am looking for more detailed info on the sunshop store software which so far doesn't seem to exist.

  16. Diane Vigil says:

    > what I would like is a listing of all functions and their associated variables

    Sounds good, although it sounds like you want them from me. I don't have them, and am not likely to try to compile them any time soon.

    I haven't had any real problems with Sunshop in the years I've been using it. Sorry to hear you're unable to achieve what you wish with it.

    Luckily, since your site says you're a web developer, you'll probably be able to get something going soon.

Have your say ...

First-time comments will be held for moderation (but comments are appreciated). Otherwise, just be courteous. If your name is a bunch of keywords, your comment will be deleted. Don't post links unless highly pertinent. Posters must be 16 or older.

Manage your subscriptions

Archives
© 2004-2017 DianeV Web Design Studio. All Rights Reserved.
34 queries. 0.265 seconds.