Skip to main content

Satchmo Questions

This note grew out of questions that went unanswered as I pushed through my first Satchmo install. Or, more accurately, it documents the questions that I had and still have. Rather than let them clutter and muddy my install notes, I have moved them here.

I am installing the current release of Satchmo, 0.9.2. To one that is moderately familiar with Django, but new to Satchmo, some aspects of the documentation are vague and/or confusing. Particularly stores, localsites, and apps. How do they relate to my planned implementation of an ecommerce site? I doubt that this tech note will answer those questions, but it will document my install and initial setup/configuration.

Documentation Shortcomings

I'm sure it's all quite clear to those that have been using Satchmo for a while, however, I, as a newb, find a lot of fuzziness and imprecision in the Satchmo documentation. Early on, there is mention of applications, extensions, extension modules, and projects, but they are never clearly defined. In particular:

  1. What are the entities that a developer will deal with / create to implement a typical ecommerce site? I see the words 'shop' and 'store' sometimes used interchangeably. At other times, it appears that 'shop' is used very specifically (i.e., to denote a specific part of the Satchmo implementation). Very confusing.
  2. How in the world does 'site' (as in 'localsite') relate to a shop (or is it a store?)? Since it appears that 'multishop' (whatever that is) is required to truly implement implement multiple sales venues, it at least superficially appears that, by default, people are only implementing a single sales venue. If so, why am I concerned about both a site and a store (or is it a shop?)?
  3. What do SHOP_BASE and SHOP_URLS do? Do I need to set them, or can I leave them alone? Does 'SHOP' refer to my shop (i.e., my store?) or does it refer to the satchmo/apps/satchmo_store/shop directory, or???
  4. Yes, what is clonesatchmo for? Just a quick and dirty example so I can see Satchmo run? Or is it a legitimate first step in bootstrapping a new site?

I hope it doesn't sound like I'm complaining, as that isn't my purpose. Rather, I'm just attempting to provide some feedback as an outsider coming to Satchmo cold (though not without Djano experience). I know that all of this is boring, and perhaps seen as 'trivial', yet if the project's goal is to make Satchmo easy for people to adopt, the issues should be addressed in some way. As all this becomes clearer to me, I'l put together a writeup to share.

A final nit: portions of the installation instructions specify the use of pip, while other portions specify the use of easy_install.

Application Structure created by creates a Satchmo app with the following structure:

store ---->
            localsite ---------->
            static -------------> css ------> ...
            templates ---\        images ---> ...
        |        js -------> ...
                         \------> shop -----> email ---> ...
                                              pdf -----> ...

Store vs. localsite vs. ...

I am on thin ice in this section... Something here could easily be incorrect. Use with caution.

In this section, words in bold are intended to be used in a very precise manner and are to be interpreted in a Satchmo context. In other words, words in bold are used (often inconsistently or vaguely) in Satchmo documentation, but they clearly have specific meanings within the Satchmo world. I attempt to clarify their meanings in this section.

A store can contain one or more sites. A site is an ecommerce venue with a single cohesive identity and product inventory. The command, by default, creates a store named store and a site named localsite.

Here lies one of the great Satchmo mysteries. Something called multisites exists, or is being worked on ( That would seem to imply that Satchmo is currently unisite or monosite. If so, why then create a Django app named store with a localsite inside it? Why the store/site distinction?

I am going to make a few guesses here. Yes, I could just read the code as it is popular to suggest, but I don't have days to spend on it at the moment.

Initially, I expected that a single Satchmo deployment could support multiple stores (note the absence of a bold font -- I am using store in the generic sense here). In other words, a Satchmo deployment could support online stores for Bob's Neckties, Cletus's Boudin, and Mary's Guns. This would imply a separate admin for each, as well as separate ordering, payment, etc. Complicated and involved stuff. I suspect that this is not present in Satchmo.

So, why the structure created by clonesatchmo? Maybe it is indeed possible to have multiple sites, but only under a single umbrella store. For example, if Bill Smith is an artist, Bill could setup a Satchmo store (i.e., common admin, ordering, payment) with multiple sites. E.g., Bill might have three sites selling his various forms of art: Bill's Photographs, Bill's Pencil Sketches, and Bill's Ceramics. Each site would be a different web destination and have their own look and feel and inventory, but purchases and fulfillment would all be driven through a single setup, namely Bill's store. The ability to do this doesn't seem so useful, or, at least, doesn't seem to be a common need. If that perception is accurate, then it doesn't make much sense to implement it. The Satchmo authors aren't dummies, so why would they do this? I don't know. Maybe I totally out in the weeds here. I'm really grasping at straws, trying to make sense of the terminology

Code changes that you make to a store, generally, apply equally to all sites. Code changes that you make to a single site, generally, do not affect other sites in the store.

Initial Setup

I assume that you ran clonesatchmo with the defaults.

Per Bruce Kroeze's suggestions...:

1. In store/ change the base URL to the localsite app:

  1. In store/localsite/, import the base store urls:

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

3. In store/, ensure that store.localsite is the last app in INSTALLED_APPS.

The bulk of your implementation should go in localsite.

Debug Toolbar

I strongly recommend that you install the Django Debug Toolbar because it is an excellent tool to use in helping to figure out, among other things, which templates are being used in rendering a page.


Let's test a couple of simple customizations convince ourselves that our configuration will work going forward. We will make a customization to store, which will affect all sites that are contained within store. We'll also make a change that affects only a single site contained within the store.

Affecting One Site

Let's assume that our store, store, is hosting multiple sites. Those sites are name localsite-1, localsite-2, etc. The directory structure of the Django application looks something like:


We wish to change the contents of the footer for a single site, localsite-1, leaving the others unmolested.

If we explore $S, we'll find that the footer is defined in $S/apps/satchmo_store/shop/templates/base.html. So, to override the footer behavior, we'll have to create store/localsite-1/templates/shop/base.html with the following contents:

{% extends "base.html" %}
{# override this template if you want your shop template to be different than your base template #}

{% block footer %}
Powered by RLBurns.
{% endblock footer %}

Affecting All Sites

Let's override behavior in $S/apps/satchmo_store/shop/templates/shop/base.html to store/templates/shop/base.html