1001 Postcards Love Love Love Meep Meep ZenZodiac DailyQuotation

Love is space and time made directly perceptible to the heart.

- MARCEL PROUST (1871-1922)

cpshop installation guide



why cpshop?




installation guide

using cpshop as your site's homepage

using cpshop filters

using cpshop hooks




download area (password required)




Please note: As of Friday, May 3, 2013, cpshop is officially retired, and is no longer for sale. details

Click here for a printable version of these instructions.

cpshop is incredibly easy to install. If you've installed perl scripts in the past, then you can probably guess how this works. If you prefer a little hand-holding, however, then here you are. Every step of the way is covered in exhaustive, even unnecessary detail.

Keep in mind that I really do cover every ridiculous detail in here, so if you know what you're doing feel free to skim.


  • make your template
  • upload your script
  • create "cpcache", "cplogs", "cpbackup", and optionally "cpoutput" and "cphooks" sub-directories
  • set permissions
  • set program options
  • enter your dummy store ID
  • try it out
Step One: Make Sure You've Got Everything

This is what you'll need to have to set up cpshop:

  • the files that come with the cpshop distribution:
    • the main script: cpshop.cgi
    • the admin script: cpadmin.cgi
    • the library files: cpdata.lib, cplogin.lib and cppage.lib
    • the configuration file: cpshop.cgi.config
    • the language files (all ending in .lang)
    • the (optional) image swap file: cpshop.cgi.images
    • the template file: cptemplate.html
  • access to a web server that can run CGI scripts (basically anything but a free webhost like Geocities)
  • a text editor -- NotePad will do, but I prefer TextPad
  • an FTP program to transfer files onto your server, like WS_FTP LE (which is freeware)
  • the URL (web address) you want cpshop located at. For example, if your website is located at, your cgi directory is called cgi-bin, you want the script files located in a subdirectory called store, and you want the main script to be called cpshop.cgi, then the URL would be:
Step Two: Create Your Template

Here's the most creative part of the process. Essentially, make an HTML page with special tags marking where certain content will go -- your cpshop distribution should have come with a demo file called cptemplate.html, which you can edit if you prefer. I'll assume here you call the template "cptemplate.html", though you can really call it anything you want.

List of tags:

  • <[title]> recommended
    The title of the page.
  • <[keywords]> recommended
    Keywords for the store, for search engines. Placed inside the keywords meta tag.
  • <[description]> recommended
    Description of the store, for search engines. Placed inside the description meta tag.
<meta type=keywords value="<[keywords]>">
<meta type=description value="<[description]>">
  • <[content]> required
    The main content generated by cpshop. This can go anywhere in the body of your template, typically where you'd put the main content for your site. Keep in mind that this space should be at least 450-500 pixels wide, in order to fit.
  • <[cart]> optional
    Link to the shopping cart. This is especially handy if you turn off the linkbar.
  • <[breadcrumb]> optional
    This tag can be used if you'd like to include the breadcrumb link navigation on your page, like Home Page > Store Name > Product Name. cpshop can automatically incorporate this into your design, so don't use it unless you want to incorporate it more interestingly in your site.
  • <[sidebar]> optional
    Displays the sidebar, based on your sidebar display settings in cpadmin.
  • <[prev]> optional
    Displays a link to the previous category, using the value of the "Previous Link" option on the admin screen as the link text.
  • <[prevname]> optional
    Displays a link to the previous category, linking to it by its name.
  • <[next]> optional
    Displays a link to the next category, using the value of the "Next Link" option on the admin screen as the link text.
  • <[nextname]> optional
    Displays a link to the next category, linking to it by its name.
  • <[storeid]> optional
    On thumbnail pages and product pages, this value will be replaced the the Store ID code. This is valuable for creating custom links and images per-store, like <img src="/thumbnails/<[storeid]>.jpg">.
  • <[productnumber]> optional
    On product pages this value will be replaced the CafePress product number. I'm not sure why you'd need this, but here it is.
The full list of template tags is maintained here.

Here is an example of a very typical (and very boring) looking template. Feel free to cut-and-paste it, if you'd like to use it as a starting point:

Some hints in creating your template:

  • Reference all links and images with full or absolute links. NO RELATIVE LINKS. Because the page will be perceived by the browser as coming from the same location as the script, relative links (links that are based on the URL of the current page) are a no-no. For example:
    • <a href="map.html">map</a> - BAD
    • <a href="../../map.html">map</a> - BAD
    • <a href="/aboutus/map.html">map</a> - GOOD
    • <a href="">map</a> - GOOD
    This goes for images, background tiles, page links, image map links, javascript URLs -- everything that includes a web address.
  • You aren't limited to creating just one template. cpshop supports a default template, a product page template, and a thumbnail page template. If either of the latter two are missing, cpshop will use the default template. This is handy if you want a special layout for thumbnail pages (like having one large detailed design image, and no actual thumbnail graphics).
  • The quickest way to create a template for your site:
    1. Fire up your handy-dandy text editor, and open a new document. Save that new document as "cptemplate.html".
    2. Using your web browser, view the source of a typical page on your site (View->Source), copy everything, paste it into your new document, and save it.
    3. Add a <base href="originalpageurl"> tag to the <head> of the document, but replacing the "originalpageurl" part with the full URL of the page you got the source from (don't forget the http:// part!).
    4. Replace the title of the document (near the top, in between the <title> and </title> tags) with <[title]>.
    5. Find the main content area of the page, select all of it, delete it, and type <[content]> in its place.
    Now you have your template file. Once you get this working you can go back and tweak it, make changes, etc.

Step Three: Rename cpshop.cgi and cpshop.cgi.config/cpshop.cgi.images (optional)

If you want to, you can rename cpshop.cgi to something else, like "", "cpshop", or "mystore".

If you do rename cpshop.cgi, you also have to rename cpshop.cgi.config and cpshop.cgi.images to match. So if you rename cpshop.cgi to, then rename cpshop.cgi.config to, and cpshop.cgi.images to

For the purposes of these instructions, I'll assume the name of the main script is still cpshop.cgi, the config file is still cpshop.cgi.config, and the image swap file is still cpshop.cgi.images.

Step Four: Set Up Your Dummy Store

No, you're not selling dummies. :) The Dummy Store serves two purposes: to tell cpshop which store to use as the base store for the cart and checkout process, and to allow you to redirect your visitors to cpshop from your shop.

If you don't have a premium shop, then do nothing for this step. Later on, however, I recommend you use the default entry (cpdefault) in the "Dummy Store ID" field in cpadmin, which will give your cart a plain white appearance (which is better than the heavily-branded CafePress look-and-feel).

If you do have a premium shop, and you're just planning on using cpshop for that shop, then I generally recommend you just enter that premium shop ID into the "Dummy Store ID" field in cpadmin (which you'll do when you're setting program options in step 8). However, if you'd also like visitors to be automatically bounced from your CafePress store to your cpshop store, then you should follow these instructions:

  1. Login to CafePress.
  2. Find your store in the list of stores, and click the "Customize" link next to it.
  3. Scroll down to the bottom of the customization page, and in the "Store Description" box, enter this code, changing the URL to the correct final address you plan to use for cpshop.cgi:

    Then press the submit button to save your changes.

Step Five: Set The Admin Password

Open cpadmin.cgi in your text editor (once again, like Notepad), and change the password to something you can remember, but most people wouldn't think of. The password is located near the top of the script, between the quotes: $password = "mypass"

Later on, when you access the admin screen, you'll use this password to login. So don't forget it.

Step Six: Upload The Scripts

(Before you upload, make sure the first line in both cpshop.cgi and cpadmin.cgi points to the correct location of perl on your server. If you're not sure where it is [usually #!/usr/bin/perl or #!/usr/local/bin/perl] then try typing which perl from the telnet command line, or ask your system administrator.)

Using your FTP client, upload the script files to the server, along with any templates you've created, placing them in your cgi-bin directory (they can be in a sub-directory, like /cgi-bin/store/). Please note:

  • They should be in the directory you refered to earlier, when you created your dummy store.
  • Make sure you upload all script files in ASCII mode!
  • Be sure to set your permissions correctly. cpshop.cgi and cpadmin.cgi should be world-executable, the configuration file should be world-writable, and everything else should be world-readable:
    chmod 644 *
    chmod 766 cpshop.cgi.config
    chmod 755 cpshop.cgi cpadmin.cgi

Step Seven: Create Special Sub-Directories

After setting up these directories, cpshop can cache CafePress' pages, speeding up loading time for your visitors, decrease server load for both you and CafePress, and add logging capabilities to your store.

  1. In the same directory as your three scripts, create three new sub-directories called "cpcache", "cplogs", and "cpbackup".
  2. Make both directories world-readable and world-executable (chmod 777 cpcache cplogs cpbackup).
Easy, ain't it?

Note: Starting with version 2.0rc12, cpshop supports Output Caching, which speeds up program output even more, decreasing CPU usage dramatically. It does so at the cost of disk space, however, so the functionality is optional but highly recommended. To enable Output Caching, you should create a fourth directory called "cpoutput" and also chmod it to 777.

Note 2: Starting with version 2.3, cpshop supports Hooks, which allow you to enter custom HTML that only appears on certain pages. If you want to use hooks, you'll want to create another directory called "cphooks", and then go read up on using cpshop hooks.

Step Eight: Set Program Options

Load cpadmin.cgi from the browser. For example, if your cpshop.cgi file is located here:
then cpadmin.cgi is likely located here:

Enter your password on the password screen, and press the submit button to get the admin screen

If you've created multiple cpshops, you can use the dropdown box at the top of the admin screen to select the correct shop.

On the admin screen you can customize everything about your cpshop store. Everything is explained in place, so I won't bother doing it here. Just make sure you follow the instructions as closely as possible, and press the "save all changes" button when you're done.

Step Nine: Testing

Well, you've done everything you were supposed to do. Now try accessing the script from your browser. It should work like a charm.

(Of course, if it doesn't, then , and I'll try to help. But first make sure you uploaded the scripts in ASCII mode, and check your permissions to make sure they're all correct! You can also check out the FAQ and the message board.)