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.2.3 properly installed.

A Quick Note About Installing Dependencies

Python allows you to install applications in multiple ways: you can use the commands easy_install or pip; you may also manually install them by:

• linking the packages into your site-packages directory, or
• use .pth files to add each to your python path.

All of these will work fine with Satchmo, but in the interest of keeping this as straightforward as possible, we show how to install the packages with either:

• easy_install, or
• python setup.py install on a source code checkout (with mercurial)

Note

The provided egg and tar files by the various dependencies may not be the most current installation, so you should ensure that the version recommended by satchmo (see Requirements) is available via easy_install before proceeding.

Installing Dependencies

1. Install setuputils by following the instructions on the 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://www.satchmoproject.com/snapshots/trml2pdf-1.2.tar.gz
   easy_install PyYAML
   

   Note

   If you have the old Python 2.4 installed, you should use also the old version of python-yaml provided by your distribution, not the latest PyYAML from pipy. If you have Python 2.4 installed, you will need to install elementtree also:

   easy_install elementtree
   

3. Install Python Imaging Library. There are multiple options for installing this application; please use one of the options below:

   • Download the binary from the PIL site and install.

   • Use your distribution’s package manager. For Ubuntu:

     sudo apt-get install python-imaging
     

4. Install Reportlab based on the description for your OS here

5. Install django-threaded-multihost:

   • Check out from source:

     hg clone http://bitbucket.org/bkroeze/django-threaded-multihost/
     cd /path/to/django-threaded-multihost
     python setup.py install
     

6. Install django-app-plugins:

   • Check out the satchmo-enhanced version:

     hg clone http://bitbucket.org/bkroeze/django-caching-app-plugins/
     cd /path/to/django-caching-app-plugins
     python setup.py install
     

7. Install sorl-thumbnail:

   • Using pip:

     pip install sorl-thumbnail==3.2.5
     

8. Install signals-ahoy:

   • Check out from source:

     hg clone http://bitbucket.org/bkroeze/django-signals-ahoy/
     cd /path/to/django-signals-ahoy
     python setup.py install
     

9. Install livesettings:

   • Check out from source:

     hg clone http://bitbucket.org/bkroeze/django-livesettings/
     cd /path/to/djang-livesettings
     python setup.py install
     

   New in version 0.9.1.

10. Install keyedcache:

    • Check out from source:

      hg clone http://bitbucket.org/bkroeze/django-keyedcache/
      cd /path/to/django-keyedcache
      python setup.py install
      

    New in version 0.9.1.

11. Satchmo has two types of documentation: Sphinx and docutils. Sphinx is used to generate this document, while docutils are useful for the auto-generated admin documentation.

    You may choose to install these dependencies by running:

    easy_install Sphinx
    easy_install docutils
    

12. Satchmo also uses South for database migrations. You may also install it:

    easy_install South
    

    See also

    Satchmo Migrations and Upgrades for more information on how migrations in Satchmo should be applied.

    New in version 0.9.1.

13. If you use the Fedex shipping module, you will need to install 2 additional modules:

    easy_install fedex
    easy_install suds
    

14. Install django-registration:

    • Check out from source:

      hg clone http://bitbucket.org/hynekcer/django-registration/
      cd /path/to/django-registration
      python setup.py install
      

Installing Satchmo into your path

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

2. Install satchmo onto your system:

   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.

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

Build Your Store With clonesatchmo

In order to quickly get you up and running, satchmo includes a helper script that will get a new sample store up and running quickly.

1. Build a starter store using clonesatchmo:

   python /home/user/src/satchmo-trunk/scripts/clonesatchmo.py
   

The clonesatchmo program will do everything described in Settings. At a high level it:

• Creates a directory for your store (defaults to simplestore)
• Also creates a localsite directory for your customizations (defaults to localsite)
• Copies a valid settings.py and local_settings.py file
• Copies your static directory in place
• Copies a valid urls.py file
• Synchs your database (using sqlite)
• Loads l10n data
• Loads a sample store

Using this process is the recommended way to get your store up and running. Once you are comfortable with this store, you can dive into modifying your Settings file or making other changes.

View the Demo Store

After you have completed your initial install, you can check out your demo store using the commands below.

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.

Troubleshooting

If after following these steps, you have errors or can not get the store to work, satchmo includes a custom command to check your system’s configuration. To check your system out:

python manage.py satchmo_check
Checking your satchmo configuration.
Your configuration has no errors.

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

Useful Links

Django installation guide