Getting started



Django-machina uses Markdown (django-markdown) by default as a syntax for forum messages, but you can change this in your settings.


Install django-machina using:

pip install django-machina


Please remember that django-machina is currently in beta. It is not yet suitable for production environments.

Project configuration

Django settings

First update your INSTALLED_APPS in your project’s settings module. Modify it to be a list and append the django-machina‘s apps to this list:

from machina import get_apps as get_machina_apps


  # Machina related apps:
] + get_machina_apps()


As previously stated, Markdown is the default syntax used for forum messages.

Django-machina uses django-mptt to handle the tree of forum instances. Search capabilities are provided by django-haystack.

Then update your TEMPLATE_CONTEXT_PROCESSORS setting as follows:

  # ...
  # Machina

Add the machina.apps.forum_permission.middleware.ForumPermissionMiddleware to your MIDDLEWARE_CLASSES setting:

    # ...
    # Machina

Edit your TEMPLATE_DIRS setting so that it includes the django-machina‘s template directory:

from machina import MACHINA_MAIN_TEMPLATE_DIR

  # ...

Edit your STATICFILES_DIRS setting so that it includes the django-machina‘s static directory:

from machina import MACHINA_MAIN_STATIC_DIR

  # ...

Finally you have to add a new cache to your settings. This cache will be used to store temporary post attachments. Note that this machina_attachments cache must use the django.core.cache.backends.filebased.FileBasedCache backend, as follows:

  'default': {
    'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
  'machina_attachments': {
    'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
    'LOCATION': '/tmp',

Django-haystack settings

Django-machina uses django-haystack to provide search for forum conversations. Django-haystack allows you to plug in many search backends so you may want to choose the one that best suits your need.

You can start using the basic search provided by the django-haystack‘s simple backend:

  'default': {
    'ENGINE': 'haystack.backends.simple_backend.SimpleEngine',

You can also decide to use a more powerfull backend such as Solr or Whoosh:

  'default': {
    'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
    'PATH': os.path.join(PROJECT_PATH, 'whoosh_index'),

Database and migrations

Django-machina only provides new-style migrations. So if you are using Django 1.8 or higher, just use the syncdb or migrate commands:

python migrate

URLs configuration

Finally you have to update your main module in order to include the forum’s URLs and the django-markdown‘s URLs:

from import board

urlpatterns = patterns(
  # [...]

  # Apps
  url(r'^markdown/', include( 'django_markdown.urls')),
  url(r'^forum/', include(board.urls)),

Creating your first forums

You can now navigate to in order to visualize the index of your forum board. As you should see no forum have been created yet. Django-machina does not ship with pre-created forums, so you should navigate to your administration panel and create some forum instances.


A common practice when creating forums is to embed them in categories in order to better organize the tree of forum instances. Please refer to Glossary if you do not know what a category is in a forum tree.

Congrats! You’re in.