Setup

If you’re starting from a Django project without Wagtail integration and you want to add a blog site to your project, please follow the steps outlined under Standalone blog app. If you are already using Wagtail, refer to Installation on top of Wagtail.

Standalone blog app

1. Install Puput and its dependencies via pip install puput.
2. Append PUPUT_APPS to INSTALLED_APPS in your settings.

from puput import PUPUT_APPS

INSTALLED_APPS += PUPUT_APPS

This includes Puput, Wagtail’s apps and certain third-party dependencies. If you are already referencing one of these apps in your INSTALLED_APPS list, please include the following apps manually in order to avoid app collisions:

INSTALLED_APPS = (
    ...
    'wagtail.core',
    'wagtail.admin',
    'wagtail.documents',
    'wagtail.snippets',
    'wagtail.users',
    'wagtail.images',
    'wagtail.embeds',
    'wagtail.search',
    'wagtail.sites',
    'wagtail.contrib.redirects',
    'wagtail.contrib.forms',
    'wagtail.contrib.sitemaps',
    'wagtail.contrib.routable_page',
    'taggit',
    'modelcluster',
    'django_social_share',
    'puput',
)

3. Add Wagtail’s required middleware classes to MIDDLEWARE_CLASSES in your Django settings.

MIDDLEWARE_CLASSES = (
    ...
    'wagtail.core.middleware.SiteMiddleware',
    'wagtail.contrib.redirects.middleware.RedirectMiddleware',
)

4. Add the request context processor to the TEMPLATE_CONTEXT_PROCESSORS structure in your Django settings.

TEMPLATE_CONTEXT_PROCESSORS = (
    ...
    'django.template.context_processors.request',
)

5. Set the WAGTAIL_SITE_NAME variable to the name of your site in your Django settings.

WAGTAIL_SITE_NAME = 'Puput blog'

6. Configure the MEDIA_ROOT and MEDIA_URL settings as described in the Wagtail Docs.

MEDIA_ROOT = os.path.join(PROJECT_ROOT, 'media')
MEDIA_URL = '/media/'

7. Place Puput’s URLs at the bottom of the urlpatterns. It also includes Wagtail’s URLs.

urlpatterns = [
    ...
    path(r'', include('puput.urls')),
]

8. To make your Django project serve your media files (e.g. things you upload via the admin) during development, don’t forget to add this to your urlpatterns:

from django.conf import settings

if settings.DEBUG:
    import os
    from django.conf.urls.static import static
    from django.views.generic.base import RedirectView
    from django.contrib.staticfiles.urls import staticfiles_urlpatterns

    urlpatterns += staticfiles_urlpatterns() # tell gunicorn where static files are in dev mode
    urlpatterns += static(settings.MEDIA_URL + 'images/', document_root=os.path.join(settings.MEDIA_ROOT, 'images'))
    urlpatterns += [
        (r'^favicon\.ico$', RedirectView.as_view(url=settings.STATIC_URL + 'myapp/images/favicon.ico')),
    ]

9. Run python manage.py migrate and python manage.py puput_initial_data to load initial data to start a blog site.
10. Open your browser at http://127.0.0.1:8000/blog/ to view your blog home page. Go to http://127.0.0.1:8000/blog_admin/ to view the admin site and edit your content.

Installation on top of Wagtail

1. Install Puput and its dependencies via pip install puput.
2. Add puput, wagtail.contrib.sitemaps and wagtail.contrib.routable_page and django_social_share to INSTALLED_APPS in your Django settings.
3. If you have previously defined Wagtail URLs in your patterns, set the PUPUT_AS_PLUGIN setting to True. This will avoid duplicate inclusion of Wagtail’s URLs when you include Puput’s URLs.
4. Include Puput’s URLs in your patterns before Wagtail’s URLs.

urlpatterns = [
    ...
    url(r'', include('puput.urls')),
    url(r'', include(wagtail_urls)),
]

5. Run python manage.py migrate.

Docker

If you want to run Puput in a Docker container please visit docker-puput for detailed instructions.