Brian McKinney

For a project I am working on, I had to figure out a quality shopping cart app to use. I tried a couple mainstream solutions and then I found out about Satchmo, a Django-based shopping cart. This seemed like a perfect solution, it had all the power and easy configuration of Django built right in. However, I had some difficulties getting it up and running. Needless to say, I thought some notes on installation might be useful to someone who uses Webfaction and wants to try it out.

Obviously, any modifications you make to your account based on this tutorial, you are responsible for. I do not take responsiblity for any liability or downtime you incur as a result of this tutorial. This tutorial in intended to be carried out on a server that is not production, in case there is downtime or problems resulting from installing Satchmo. Follow at your your own risk!

Setup your account to run Satchmo

The first thing you'll need to do is make sure you have an environment conducive to running Satchmo on Webfaction. This tutorial assumes you are starting from scratch. Extra scratch. Go to your panel (http://panel.webfaction.com) and sign in to begin.

Setup django from the Webfaction control panel

1. Mouse over "Domains/websites" and select "Applications" from the menu
2. Click on the "Add New" icon (icon just below the options heading, with the green plus sign)
3. In the Name field, type "django_apps"
4. In the App Type field, select "Django (0.96) with Python (2.5)"
5. Click on the "Create" button to install Django
6. A success page should appear once Django has been installed

Add a static area for media files

1. Mouse over "Domains/websites" and select "Applications"
2. Click on the "Add New" icon
3. In the "Name" field, type a memorable name for your title for your media files (ex. somesite_media)
4. In the dropdown for "App type", select "Static/CGI/PHP"
5. Click on the"Create" button
6. A success page should appear, once the media area has been created

Add a link to the admin media files

1. Mouse over "Domains/websites" and select "Applications"
2. Click on the "Add New" icon
3. In the "Name" field, type "admin_media"
4. In the dropdown for "App type", select "Symbolic link"
5. In the "Extra info" field, type the absolute path to your admin media (/home/username/lib/python2.5/django/contrib/admin/media)
6. Click on the "Create" button
7. A success page should appear, once the admin media area has been created

Add a redirect application

Most modern websites serve the same content to both a www prefix and a non-www prefix domain name. When using Satchmo, you will likely want to utilize a single domain (like somesite.com) and redirect the www version or vice-versa. At first I was trying to support both www and non-www versions and it caused problems with user accounts and security certificates. Installing a redirect with webfaction is no problem, and is the correct way to handle this situation. Note: Versions of this tutorial before March 3, 2008 did not illustrate how to install this redirect.

1. Mouse over "Domains/websites" and select "Applications"
2. Click on the "Add New" icon
3. In the "Name" field, type a memorable name for your title for your redirect (ex. redirect)
4. In the dropdown for "App type", select "Static/CGI/PHP"
5. Click on the "Create" button
6. A success page should appear, once the redirect app has been created

Connect your domain to Webfaction

1. Assuming you've already pointed your DNS at Webfaction, mouse over "Domains/websites" and select "Domains"
2. Click on the "Add new" icon to add a new domain
3. In the name field, type the name of the domain exactlly (ex: somesite.com)
4. Click on the "Add new" icon to add a new prefix
5. In the field that appears, type "www"
6. Click the "Create" button
7. You will get a success page that tells you your item has been created
8. Visiting your domain should now result in a "Site not configured" message

Connect your website to the domain

1. Mouse over "Domains/websites" and select "Websites"
2. Click on the "Add new" icon to add a new website
3. In the "Name" field, type the name of the site (ex: somesite)
4. Do not check the box for Https
5. In the "Subdomains" box, select the domain name you will want for the actual main site (ex: somesite.com OR www.somesite.com)
6. Under the "Site Apps" area, click on the "Add new" icon
7. In the "App" field, select "django_apps", then in the "URL path" field type "/"
8. Again, under the "Site Apps" area, click on the "Add new" icon
9. In the &"App" field, select the name of your media area. In the "URL path" field type "/media"
10. Again, under the "Site Apps" area, click on the "Add new" icon
11. In the "App" field, select the name of your admin media area. In the "URL path" field type "/admin_media"
12. Click the "Create" button
13. A success page should display, telling you your item has been created
14. Mouse over "Domains/websites" and select "Websites"
15. Click on the "Add new" icon to add a new website
16. In the "Name" field, type the name of the site and add a "-secure" (ex: somesite-secure)
17. This time, check the box for Https
18. In the "Subdomains" box, select the same domain name as above
19. Under the &"Site Apps" area, click on the "Add new" icon
20. In the "App" field, select "django_apps", then in the "URL path" field type "/"
21. Again, under the "Site Apps" area, click on the "Add new" icon
22. In the "App" field, select the name of your media area, then in the "URL path" field type "/media"
23. Again, under the "Site Apps" area, click on the "Add new" icon
24. In the "App" field, select the name of your admin media area, then in the "URL path" field type "/admin_media"
25. Click on the "Create" button
26. You should get a success page, telling you your item has been created

Connect the redirect to the domain

1. Mouse over "Domains/websites" and select "Websites"
2. Click on the "Add new" icon to add a new website
3. In the "Name" field, type a name for the redirect (ex: www-redirect)
4. Do not check the box for Https
5. In the "Subdomains" box, select the domain name you will want to be redirected to the actual site (ex: somesite.com OR www.somesite.com)
6. Under the "Site Apps" area, click on the "Add new" icon
7. In the "App" field, select "redirect", then in the "URL path" field type "/"
8. Click the "Create" button
9. A success page should display, telling you your item has been created
10. Mouse over "Domains/websites" and select "Websites"
11. Click on the "Add new" icon to add a new website
12. In the "Name" field, type the name for the redirect and add a "-secure" (ex: www-redirect-secure)
13. This time, check the box for Https
14. In the "Subdomains" box, select the domain name you will want to be redirected to the actual site (ex: somesite.com OR www.somesite.com)
15. Under the "Site Apps" area, click on the "Add new" icon
16. In the "App" field, select "redirect", then in the "URL path" field type "/"
17. Click on the "Create" button
18. You should get a success page, telling you your item has been created

Setup your Database

For this example we are going to use MySQL, but you can obviously use postgresql if you want.

1. Mouse over "Databases" and select "Create new database"
2. Leave the "Machine" field as is
3. In the "Type" field, select "MySQL"
4. In the "Name&" field, type your account name_sa (ex: someaccount_sa) Webfaction requires that database names begin with the account name and are less then 16 characters long
5. In the "Encoding" field, leave utf8
6. Click on the "Create" button
7. A success message will appear, and a default password will be displayed
8. Make note of the name of the database, the username, and the password - located in the green text toward the top of the screen

Install and configure the Satchmo code

Now that you've setup your Webfaction environment to run Django, you should be able to visit your domain name and see the django success message. To run Satchmo, you'll need to download the satchmo code and configure it. Using a ssh client, signin to your Webfaction account to get started.

Rename your project

1. Once you've signed in, cd into your webapps directory, there should be a django_apps directory, a media directory, and a admin media symbolic link (more if you have other applications installed)

2. cd into the "django_apps" directory and rename the "myproject" directory to satchmoproject

3. edit the apache2/conf/httpd.conf direcory and change:

   SetEnv DJANGO_SETTINGS_MODULE myproject.settings
   

   to

   SetEnv DJANGO_SETTINGS_MODULE satchmoproject.settings
   

Download the Satchmo code

1. cd into your home directory

2. make a new directory called packages

3. cd into that directory and run this command if you want the newest (with the slight possiblity of bugs) code:

   svn co svn://satchmoproject.com/satchmo/trunk/ satchmo-source
   

   or this command if you want a guaranteed stable release:

   svn co svn://satchmoproject.com/satchmo/tags/0.6 satchmo-source
   

   *Note: .6 is the current stable version as of this writing. Visit the satchmo project website for the current version number*

4. Copy the satchmo-source/satchmo directory into the "packages" directory

5. cd back to your home directory and edit the .bash_profile file

6. Under the line "# User specific environment and startup programs", add "export PYTHONPATH=$PYTHONPATH:$HOME/packages"

7. Save the file and exit

8. Run the command "source .bash_profile" to reload it

9. Type "echo $PYTHONPATH" to verify that the "packages" directory has been added

10. Edit the .bashrc file

11. Under the line "## User specific aliases and functions", add "alias python=python2.5"

12. Save the file and exit

13. Run the command "source .bashrc" to reload it

Download the correct Django snapshot

This is a little tricky. Satchmo is very much on the bleeding edge of Django, when Django makes changes to its' code base, it often times will cause errors within Satchmo. The developers at Satchmo do a good job of keeping their versioning in line with updates to the Django code. The best approach is to get the newest code from Satchmo and Django and verify that it works. If you have major problems with incombatitbility, switch to this specific Django snapshot and keep with it until django gets a bit closer to 1.0 (backwards compatability). This step could significantly screw up other django apps you are running off of the same django installation. Proceed at your own risk.

1. cd into your Python directory (/home/username/lib/python2.5/)

2. run this command:

   svn co http://code.djangoproject.com/svn/django/trunk/ django-source
   

   or if you've had problems with the newest code, try this

   svn co -r 5947 http://code.djangoproject.com/svn/django/trunk/ django-source
   

3. The new Django code should be downloaded into the "django-source" directory

4. Copy "django-source/django" directory into the "python2.5" directory (replacing the old django files)

5. Don't forget to restart your apache!

Configure the settings files

1. Copy the "settings-customize.py", "local_settings-customize.py" and "load-data.py" from the "packages/satchmo/" directory over to the "satchmoproject" directory under "django_apps"

2. cd into the satchmoproject directory

3. Rename the settings-customize.py file to settings.py

4. Edit the settings.py file and move down to the line that says:

   DJANGO_SETTINGS_MODULE = 'satchmo.settings'
   

   change to:

   DJANGO_SETTINGS_MODULE = 'settings'
   

   Next, find the line that says:

   DATABASE_ENGINE = ""
   

   change to:

   DATABASE_ENGINE = "mysql"
   

   Next, find the line that says:

   MEDIA_ROOT = os.path.join(DIRNAME, 'static/')
   

   Change this line to:

   MEDIA_ROOT = "/home/username/webapps/*name of media directory*"
   

   Next, find the line that says:

   MEDIA_URL= "/static/"
   

   Change this line to:

   MEDIA_URL="/media/"
   

   Next, find the line that says:

   ADMIN_MEDIA_PREFIX ="/media/"
   

   Change this line to:

   ADMIN_MEDIA_PREFIX = "/admin_media/"
   

   Finally, find the line under "TEMPLATE_DIRS" that says:

   os.path.join(DIRNAME, "templates"),
   

   modify to be:

   "/home/username/packages/satchmo/templates/"
   

5. Save the file and quit

6. Rename the local_settings-customize.py file to local-settings.py

7. Edit the local_settings.py file

8. Find the database information area, which should look like this:

   DATABASE_NAME = ""
   DATABASE_PASSWORD = ""
   DATABASE_USER = ""
   SECRET_KEY = ""
   

   Enter the database information you made note of and if you would like, add a security key.

9. Find the line that says:

   CHECKOUT_SSL=False
   

   and change to:

   CHECKOUT_SSL=True
   

10. Save the file and quit

11. Restart apache

Load the sample data

1. Still within the satchmoproject directory, type the command: python load_data.py
2. A bunch of data should get created for you to play around with
3. Restart apache

Link up the media files

1. cd into your media directory ("/home/username/webapps/media")
2. Copy the image, css, and javascript folders from /home/username/packages/satchmo/static/ to the media directory.

Configure the redirect

1. create a file "/home/username/webapps/redirect/.htaccess" with the following content:

   RewriteEngine on
   RewriteCond %{HTTP_HOST} domain.com
   RewriteRule ^(.*) http://www.domain.com/$1 [R]
   

   Note: This will redirect 'domain.com' to 'www.domain.com', you may choose to do the opposite, and if so, simply switch these two in the above code.

All done!

Go to your website and view satchmo in all of its' glory. OK, seriously, now you should be able to alter your images, css, etc. and get a good online store going

Thanks for checking out the article, happy selling.