Settings

The recommended way to get a working settings file and configure your first store is to use the clonesatchmo program. However, if you would like to customize the settings by hand or dive into the details of how Satchmo’s settings are used, this portion of the documentation will be useful.

Customizing the settings

Once Satchmo is installed on your PYTHONPATH, you will need to create a new project or integrate Satchmo into an existing project. Before proceeding with the next steps, please familiarize yourself with the sample projects, see here for more.

Each of these projects show examples of how to configure Satchmo and integrate it with other Django applications. Once you are familiar with these examples, you can configure your project based on the notes below.

Additionally, there is a streamlined satchmo directory structure in the skel directory. You may use this as the basis for your store.

You need to customize the settings.py file in mystore to include the relevant satchmo information. A sample file called settings.py is available in the projects/base directory to act as a template. You may use this file as a template for settings.py or use the notes below to configure your existing one.

Please remember to ensure that your Django database connections and settings are working properly before trying to add any pieces of satchmo.

  1. Ensure that /home/user/src/mystore/settings.py has the following satchmo-specific configurations (in addition to the defaults and your other app needs):

    import os
    DIRNAME = os.path.abspath(os.path.dirname(__file__))
    LOCAL_DEV = True
    
    MEDIA_ROOT = os.path.join(DIRNAME, 'static/')
    MEDIA_URL = '/static/'
    
    MIDDLEWARE_CLASSES = (
        "django.middleware.common.CommonMiddleware",
        "django.contrib.sessions.middleware.SessionMiddleware",
        "django.middleware.locale.LocaleMiddleware",
        "django.contrib.auth.middleware.AuthenticationMiddleware",
        "django.middleware.doc.XViewMiddleware",
        "threaded_multihost.middleware.ThreadLocalMiddleware",
        "satchmo_store.shop.SSLMiddleware.SSLRedirect",
        "django.middleware.csrf.CsrfViewMiddleware",
        "django.contrib.messages.middleware.MessageMiddleware")
    
    TEMPLATE_DIRS = (os.path.join(DIRNAME, "templates"))
    TEMPLATE_CONTEXT_PROCESSORS =     ('satchmo_store.shop.context_processors.settings',
                                     'django.core.context_processors.auth',
                                     'django.contrib.messages.context_processors.messages',
                                     )
    
    INSTALLED_APPS = (
            'django.contrib.sites',
            'django.contrib.messages',
            'satchmo_store.shop',
            'django.contrib.admin',
            'django.contrib.auth',
            'django.contrib.admindocs',
            'django.contrib.contenttypes',
            'django.contrib.comments',
            'django.contrib.staticfiles',
            'django.contrib.sessions',
            'django.contrib.sitemaps',
            'registration',
            'keyedcache',
            'livesettings',
            'l10n',
            'sorl.thumbnail',
            'satchmo_store.contact',
            'tax',
            'tax.modules.no',
            'tax.modules.area',
            'tax.modules.percent',
            'shipping',
            'product',
            'product.modules.configurable',
            'product.modules.custom',
            'product.modules.downloadable',
            'product.modules.subscription',
            'payment',
            'payment.modules.dummy',
            'payment.modules.giftcertificate',
            'satchmo_utils',
            'app_plugins',
            )
    
    AUTHENTICATION_BACKENDS = (
        'satchmo_store.accounts.email-auth.EmailBackend',
        'django.contrib.auth.backends.ModelBackend'
        )
    
    #### Satchmo unique variables ####
    #from django.conf.urls import patterns, include
    SATCHMO_SETTINGS = {
                        'SHOP_BASE' : '',
                        'MULTISHOP' : False,
                        'SSL'       : False,
                        #'SHOP_URLS' : patterns('satchmo_store.shop.views',)
                        }
    
    # Load the local settings
    from local_settings import *
    

Note

In order for the admin site to work properly, you must have satchmo_store.shop placed before django.contrib.admin

  1. Copy the local_settings file to mystore:

    cp /home/user/src/satchmo-trunk/satchmo/projects/base/local_settings.py \
        /home/user/src/mystore/local_settings.py
    
  2. You will need to verify the values assigned to the following items in local_settings.py:

    SITE_NAME
    CACHE_BACKEND
    CACHE_TIMEOUT
    SITE_DOMAIN
    LOGDIR
    LOGFILE
    

Note

Satchmo requires that your database be able to support utf-8 characters. This is especially important for MySQL. If you are using MySQL, you may want to use the following statement in your settings file to enforce utf-8 collation:

DATABASES['default']['OPTIONS'] = {
   'init_command' : 'SET NAMES "utf8"',
   }

Note

If you are using a Windows system, we recommend setting your MEDIA_ROOT using normalize_path as shown below:

from satchmo_utils.thumbnail import normalize_path
MEDIA_ROOT = normalize_path(os.path.join(DIRNAME, 'static/'))

Configure the rest of the required files

  1. Next, you need to configure your urls.py file. The most simple urls.py file would look like this:

    from django.conf.urls import *
    from satchmo_store.urls import urlpatterns
    
  2. If you have additional urls you would like to add to your project, it would look like this:

    from django.conf.urls import *
    from satchmo_store.urls import urlpatterns
    
    urlpatterns += patterns('',
        (r'test/', include('simple.localsite.urls'))
    )
    

3. Ensure that you have a template directory setup. You only need to place templates in the directory if you are overriding existing templates.

After you have installed everything, you should have a directory structure that looks similar to this:

mystore
    |-- __init__.py
    |-- local_settings.py
    |-- manage.py
    |-- satchmo.log
    |-- settings.py
    |-- simple.db
    |-- static
    |   |-- css
    |   |   |-- blackbird.css
    |   |   |-- jquery.autocomplete.css
    |   |   `-- style.css
    |   |-- images
    |   |   |-- blackbird_icons.png
    |   |   |-- blackbird_panel.png
    |   |   |-- productimage-picture-default.jpg
    |   |   |-- productimage-picture-default_jpg_85x85_q85.jpg
    |   |   `-- sample-logo.bmp
    |   `-- js
    |       |-- blackbird.js
    |       |-- jquery.ajaxQueue.js
    |       |-- jquery.autocomplete.js
    |       |-- jquery.bgiframe.js
    |       |-- jquery.cookie.js
    |       |-- jquery.form.js
    |       |-- jquery.js
    |       |-- satchmo_checkout.js
    |       |-- satchmo_pay_ship.js
    |       |-- satchmo_product.js
    |       `-- satchmo_store.js
    |-- templates
    `-- urls.py

Test and Install the Data

  1. Now, you should be ready to go. In order to test your Satchmo setup, execute the following command (from the mystore directory):

    python manage.py satchmo_check
    Checking your satchmo configuration.
    Your configuration has no errors.
    
  2. If any errors are identified, resolve them based on the error description.

  3. Sync the new satchmo tables:

    python manage.py syncdb
    
  4. Load the country data stored in the l10n application:

    python manage.py satchmo_load_l10n
    
  5. (Optional) Load the demo store data:

    python manage.py satchmo_load_store
    
  6. (Optional) Load the US tax table:

    python manage.py satchmo_load_us_tax