Getting started

Requirements

Note

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

Installation

Install django-machina using:

$ pip install django-machina

Project configuration

Django settings

First update your INSTALLED_APPS in your project’s settings module. Modify it so that it includes the machina’s dependencies and the machina’s own applications as follows:

INSTALLED_APS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.admin',

    # Machina dependencies:
    'mptt',
    'haystack',
    'widget_tweaks',

    # Machina apps:
    'machina',
    'machina.apps.forum',
    'machina.apps.forum_conversation',
    'machina.apps.forum_conversation.forum_attachments',
    'machina.apps.forum_conversation.forum_polls',
    'machina.apps.forum_feeds',
    'machina.apps.forum_moderation',
    'machina.apps.forum_search',
    'machina.apps.forum_tracking',
    'machina.apps.forum_member',
    'machina.apps.forum_permission',
)

Note

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

Then modify your TEMPLATES settings so that it includes the django-machina’s template directory and the extra metadata context processor:

from machina import MACHINA_MAIN_TEMPLATE_DIR

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': (
            # ...
            MACHINA_MAIN_TEMPLATE_DIR,
        ),
        'OPTIONS': {
            'context_processors': [
                # ...
                # Machina
                'machina.core.context_processors.metadata',
            ],
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            ]
        },
    },
]

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

MIDDLEWARE = (
    # ...
    # Machina
    'machina.apps.forum_permission.middleware.ForumPermissionMiddleware',
)

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

from machina import MACHINA_MAIN_STATIC_DIR

STATICFILES_DIRS = (
    # ...
    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:

CACHES = {
    '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:

HAYSTACK_CONNECTIONS = {
    'default': {
        'ENGINE': 'haystack.backends.simple_backend.SimpleEngine',
    },
}

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

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

Note

It should be noticed that you’ll have to run the update_index Haystack’s command once your forum is properly set up in order to make your topics & posts searchable.

Database and migrations

Just use the migrate command to install the models:

$ python manage.py migrate

URLs configuration

Finally you have to update your main urls.py module in order to include the forum’s URLs:

from django.urls import include, path
from machina import urls as machina_urls

urlpatterns = [
    # [...]
    path('forum/', include(machina_urls)),
]

Creating your first forums

You can now navigate to http://127.0.0.1:8000/forum/ in order to visualize the index of your forum board (and you can use the forum:index URL name to add a link toward the forum in your Django templates). As you should see no forums 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.

Note

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.