Table Of Contents

Previous topic

Quick Start

Next topic

Basic Configuration

Documentation Version:

Installation

This guide is the Satchmo installation process. It is meant to be a cookbook approach for most users. Advanced users may wish to modify this in order to integrate into their own projects. For the truly impatient, you may look at the Quick Start for the fastest way to get a store up and running.

This guide assumes you are working on a unix variant and that you are installing it somewhere into a directory you have write access to. In the below example, we use /home/user/src. You are expected to modify the path to fit your needs.

Warning

You must have Django 1.1.x properly installed and all of the dependencies mentioned in the requirements section properly installed.

The easiest way to install satchmo requirements, is to use the python setuptools program to download egg and tar packages. The next section describes one simple method to install the dependencies. You may manually install them if you wish.

Installing Dependencies

  1. Install setuputils by following the instructions on easy_install page. After installation, you should be able to run easy_install directly (assuming the install directory is in you $PATH).

  2. Install required dependencies (this may vary based on your OS of choice):

    easy_install pycrypto
    easy_install http://code.enthought.com/enstaller/eggs/rhel/3/Reportlab-2.1.0001-py2.5.egg
    easy_install http://www.satchmoproject.com/snapshots/trml2pdf-1.2.tar.gz
    easy_install django-registration
    easy_install PyYAML

Note

If you have Python 2.4 installed, you will need to install elementtree also:

easy_install elementtree

Warning

Not all dependencies are available via easy_install.

  1. Install Python Imaging Library. There are multiple options for installing this application. Please use 1 of the options below:

    - Download the binary from the PIL site and install.
    
    - Use your distributions package manager. For Ubuntu::
    
        sudo apt-get install python-imaging
    
    - Use easy_install::
    
        easy_install --find-links=http://download.zope.org/distribution PILwoTk
  2. Install django-threaded-multihost:

    - Download from http://gosatchmo.com/apps/django-threaded-multihost/
    • Unpack or check out and install:

      sudo python setup.py install
  3. Install django-app-plugins:

    • Two options, use the original, or a slightly forked version which uses Satchmo’s advanced caching system to speed up page loads.

    • (Option 1) Check out from original source:

      svn checkout http://django-app-plugins.googlecode.com/svn/trunk/ django-app-plugins-read-only
      cd /path/to/your/site-packages/dir
      ln -s /path/to/django-app-plugins-read-only/app_plugins .
    • (Option 2) Check out the forked version:

      hg clone http://bitbucket.org/bkroeze/django-caching-app-plugins/
      cd /path/to/your/site-packages/dir
      ln -s /path/to/django-caching-app-plugins/app_plugins .
  4. Install sorl-thumbnail:

    • Check out from source:

      hg clone https://sorl-thumbnail.googlecode.com/hg/ sorl-thumbnail
      cd /path/to/your/site-packages/dir
      ln -s /path/to/sorl .
  5. Install signals-ahoy:

    • Check out from source:

      hg clone http://bitbucket.org/bkroeze/django-signals-ahoy/
      cd /path/to/your/site-packages/dir
      ln -s /path/to/django-signals-ahoy/signals_ahoy

Satchmo has two types of documentation. Sphinx is used to generate this document. Docutils are useful for the auto-generated admin documentation. You may choose to install these dependencies.

  1. Optional documentation dependencies:

    easy_install Sphinx
    easy_install docutils

Note

Please note that all dependencies can be installed manually. Please visit the requirements page for details. Also, provided egg and tar files may not be the most current installation, so you should ensure that the recommended satchmo version is available via easy_install before proceeding.

Installing Satchmo into your path

  1. Use django to create your new store:

    cd /home/user/src
    django-admin.py startproject mystore
  2. Checkout the latest Satchmo release into (/home/user/src):

    hg clone http://bitbucket.org/chris1610/satchmo/

Note

If you are a bitbucket user, you may see a slightly different url than described above. You may use the generic url or one that is specific to your username. For the purposes of an install, either will work.

  1. Install satchmo into your site-packages directory:

    cd /home/user/src/satchmo-trunk
    sudo python setup.py install

Note

An alternative to running the install is ensuring that /path/to/satchmo/apps is on your python path. You may do this by placing a symbolic link to the source, adding a .pth file that points to your /satchmo/apps location or modifying your PYTHONPATH environment variable.

  1. Once the above step is completed, you should be able to import both django and satchmo:

    $ python
    Python 2.5.2 (r252:60911, Mar 12 2008, 13:39:09)
    [GCC 4.2.3 (Ubuntu 4.2.3-2ubuntu4)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import django
    >>> import satchmo_store
    >>> satchmo_store.get_version()
    '0.9-pre hg-YYYY:ZZZZZZZZZZ'

Warning

Do not attempt to progress any further on the install until the above imports work.

Customizing the settings

Now that 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 that are available in /satchmo/projects/.

There are 3 example projects stored here:

  • base
  • large
  • simple

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 choose to copy this file and use 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")
    
    TEMPLATE_DIRS = (os.path.join(DIRNAME, "templates"))
    TEMPLATE_CONTEXT_PROCESSORS =     ('satchmo_store.shop.context_processors.settings',
                                     'django.core.context_processors.auth',
                                     )
    
    INSTALLED_APPS = (
            'django.contrib.sites',
            'satchmo_store.shop',
            'django.contrib.admin',
            'django.contrib.auth',
            'django.contrib.admindocs',
            'django.contrib.contenttypes',
            'django.contrib.comments',
            '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',
            'payment',
            '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.defaults import patterns, include
    SATCHMO_SETTINGS = {
                        'SHOP_BASE' : '',
                        'MULTISHOP' : 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:

DATABASE_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.defaults 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.defaults import *
    from satchmo_store.urls import urlpatterns
    
    urlpatterns += patterns('',
        (r'test/', include('simple.localsite.urls'))
    )
    
  3. Copy over the static directory:

    python manage.py satchmo_copy_static

11. 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

View the Demo Store

  1. Start up the sample webserver to see your store:

    python manage.py runserver
  2. In order to see your sample store, point your browser to:

    http://127.0.0.1:8000/shop or http://127.0.0.1/
  3. If you want to see the admin interface, point your browser to:

    http://127.0.0.1:8000/admin
  4. Many configuration and customization settings are accessed through the url:

    http://127.0.0.1:8000/settings
  5. Additional detailed documentation can be found here:

    http://127.0.0.1:8000/admin/doc

Note

The above urls will be dependent on your Django setup. If you’re running the webserver on the same machine you’re developing on, the above urls should work. If not, use the appropriate url.

Additional Notes

Satchmo also includes a full set of unit tests. After you get your system installed, you can run the unit tests with this command:

python manage.py test