I've recently picked up a project to add a forum to a site. They have an existing site, but just want a forum added, and have also made the specification that it should be using spirit.

I had done one other project before, which we made a custom forum with django and ember.js. I had evaluated spirit at that time and due to project requirements, we decided to make our own custom forum.

During my investigation of django-spirit, it's very clear that it's not a normal package. There would be no pip install xxxx and then adding some settings. It's completely different to install Spirit, so I thought I'd write a post to share. I'll be doing this with python3 and django==1.8.16, they say that Spirit is only compatible with django 1.8, let us know if the comments if you've installed with a different django version.

Getting django-spirit up and running

You'll notice in their "docs" that there are no installation steps, and that they point you to an example project. There actually are no real docs, and you're left to figure things out on your own. If you follow the directions in the example project, you can have a new spirit forum up in minutes. The complication comes when you want to put a spirit forum into your existing site.

There are a few steps that we will go through to get the Spirit forum running: copy spirit files, install packages, add to INSTALLED_APPS, add other Spirit settings, Static Files setup, and finally normal install steps (migrate, urls).

Copy the Spirit project

First thing we need to do is get the files needed from Spirit. We can clone the repo locally with git clone https://github.com/nitely/Spirit.git. Once you have the spirit repo locally, you can then copy the spirit directory into your local project.

Install Pacakges

The next thing you should do is copy over the packages in spirit's root-level requirements.txt file into your own requirements.txt file. There might be some duplications such as Django, pytz, django-haystack or Pillow. If there is a duplicate don't copy that over. Update your project's installed packages with `pip install -r requirements.txt` after updating your requirements.txt file.

At this point you can delete the repo that you cloned - we only need the spirit directory for installation.


We have our own project settings file, and the copied spirit folder has its own settings file. The next few steps will be to copy over the required settings into our project.

There are many apps from spirit that need to be added to our INSTALLED_APPS. Since django-spirit is unconventional, you'll see a whole bunch of spirit* apps in the `spirit/settings.py` file. Copy all of those apps that begin with spirit into your own INSTALLED_APPS. You'll also find that below they have added a couple more apps (they should just have it in the INSTALLED_APPS main section...) that need to be added as well: `djconfig` and `haystack`.

Spirit Settings

Copy all the settings in `stripe/settings.py` that begin with ST_ into your project's settings file.

There's also a required middleware class from djconfig that needs to be copied into your settings.MIDDLEWARE_CLASSES called djconfig.middleware.DjConfigMiddleware.

Last but not least, you'll need to copy over the HAYSTACK_CONNECTIONS settings from spirit into your project's settings.

Static Files

If you don't yet have a STATIC_ROOT in your project, you'll need to add one. The typical setting to add is STATIC_ROOT = os.path.join(BASE_DIR, 'static'), but you can have your static root anywhere.

Finish Install & Enjoy

At this point we have a normal 3rd party package install steps. In your project urls.py file add url(r'^forum/', include('spirit.urls')), and then run ./manage.py migrate.

If you've missed some step, or I've missed one of the required integration steps, Django should tell you when you try to run ./manage.py runserver.

You should now have a working Spirit forum in your project. There are still other optional things to include such as extra middleware classes and caching, but you can now use the forum and figure out what you'd like to override.