setup.rst

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_app. If you are already using Wagtail, refer to wagtail_app.

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.