Starting a new store – real world project layout

Updated 10 July 2010

The official Installation Instructions are accurate, and will definitely work to get a store running. However, I think that many developers would like some advice about how to best lay out the directories for ease of maintenance.

Go read those docs, but then come back here for a suggested layout.

Read it? Good, let’s get to my layout.

First, you need to make a basic project structure. I make one like so:

storename/
  __init__.py
  settings_local.py
  manage.py
  settings.py
bin/
  (here are various scripts you may use for testing or whatever)
etc/
   init.d/
       storename
       sysconfig/
           storename
fixtures/
localsite/
    __init__.py
    models.py
    templatetags/
        __init__.py
media/
    css/
    images/
    js/
templates/
    storename/

I don’t use any “manage.py” commands to make this outline. I just make the directories, copy the default satchmo settings.py and local_settings.py (renaming to settings_local.py, so that they sort nicely) to the base directory, and then use “touch” to make empty files for all the other files.

Configuring your urls

In your settings file, make your base urls file be the one in your localsite app. Like so:

ROOT_URLCONF = ‘storename.localsite.urls’

Then, in your storename/localsite/urls.py file, just import the base store urls like so:

from django.conf.urls.defaults import *
from satchmo.urls import urlpatterns

For now, that’s all you have to do, but later you’ll be able to add your own special site urls without any hassle or reconfiguration.

Configuring your templates

It is particularly important not to simply copy all of Satchmo’s templates into your template directory. I think that is the single biggest mistake beginning Satchmo developers make. Why? Because if we later upgrade Satchmo or change the templatetags, you won’t get the benefit of those changes.

Instead, simply copy the templates you need to override into your template directory, leaving all the rest to be found by Django’s template resolution functionality. See my article How to Skin a Satchmo Store – Overriding Templates for more details.

Install the localsite app

Having a custom app for any store is a great thing to do.

• It will allow you to have custom urls with ease
• You can add your own templatetags which are only useful for the particular store
• It provides a convenient place to register custom listeners for Satchmo signals.

Adding the “localsite” app is merely a matter of making the three files “__init__.py”, “models.py”, and “urls.py”, and then adding it to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = (
    [...]
    storename.localsite #should usually be last
)

Now you are ready

Now you are ready to continue with the official Satchmo install instructions, but your store will be much more flexible and ready to handle the real world.

Other tutorials

• SaltyCrane’s Satchmo Installation Notes

Updates

This article was written in 2008, but I am trying to keep this up to date, please comment below if you find something wrong or or which no longer makes sense.

10 July 2010: Updated, changing a few directory names, and updating links.