DjangoCMS 3.x paste

DjangoCMS projects are created with the many components that are available for use. These components are called mods and these mods are already installed and ready to use, but they are not all enabled. You can enable or disable them, as needed.

It is always preferable to use the mods system to install new apps. You should never install a new app with pip. If you plan to integrate it into the project, always use the buildout system. Just open and edit the buildout.cfg file to add the new egg to be installed. For more details, read the buildout documentation.


This paste will appear with the name djangocms-3 in the paster templates list (with the paster create --list-templates command).

To use this paste to create a new project you will do something like :

paster create -t djangocms-3 myproject



This is the command installed to replace the script in Django. django-instance is aware of the installed eggs.

Paste template version

In your projects, you can find from which Paste template they have been builded in the project/ file where you should find the used package name and its version. So you can easily see the version doing something like :

cat project/

Note that previously (before the Epaster version 1.8), this file was containing the Epaster version, not the Paste template one, since the package didn’t exists yet.

How the Mods work

The advantage of centralizing app configurations in their mods is the project’s and are gathered together in its configuration (cache, smtp, paths, BDD access, etc.). Furthermore, it is easier to enable or disable the apps.

To create a new mods, create a directory in $PROJECT/mods_avalaible/ that contains at least one empty and a to build the app in the project and potentially its settings. The` and files in this directory will be executed automatically by the project (the system loads them after the project ones so that a mods can overwrite the project’s initial settings and urls). N.B. With Django’s runserver command, a change to these files does not reload the project instance; you need to relaunch it yourself manually.

To enable a new mods, you need to create its symbolic link (a relative path) in $PROJECT/mods_enabled. To disable it, simply delete the symbolic link.

Installation and initial use

Once your project has been created with this epaster template, you need to install it to use it. The process is simple. Do it in your project directory:

make install

When it’s finished, active the virtual environment:

source bin/active

You can then use the project on the development server:

django-instance runserver

Note is some sort of alias that mean “bind this server on my ip”, so if your local ip is “”, the server will be reachable in your browser with the url


Note the :8001 that mean “bind the server on this port”, this is a required part when you specify an IP. Commonly you can’t bind on the port 80 so allways prefer to use a port starting from 8001.


If you don’t know your local IP, you can use that is an internal alias to mean “my own network card”, but this IP cannot be reached from other computers (because they have also this alias linked to their own network card).

The first required action is the creation of a CMS page for the home page and also you should fill-in the site’s name and its domain under Administration > Sites > Sites > Add site.

Available mods


Enable Django registration and everything you need to allow users to request registration and to connect/disconnect. The views and forms are added so this part can be used.

It includes:

  • A view for the login and one for the logout;
  • All the views for the registration request (request, confirmation, etc.);
  • A view to ask for the reinitialization of a password.

In the skeleton.html template, a partial HTML code is commented. Uncomment it to display the logout button when the user is connected.

The registration process consists in sending an email (to be configured in the settings) with the registration request to an administrator responsible for accepting them (or not). Once validated, an email is sent to the user to confirm his registration by way of a link. Once this step has been completed, the user can connect.

Also, note that this app use a dummy profile model linked to User object. This profile is dummy because it implement fields for sample but you may not need all of them or you can even may not need about a Profile model, the User object could be enough for your needs. So before to use the syncdb, be sure to watch for the model to change it, then apply your changes to forms.RegistrationFormAccounts, views.RegistrationView and eventually templates.


Enable djangocms-admin-style to enhance the administration interface. Also enable django-admin-shortcuts.

admin-style better fit with DjangoCMS than admin_tools.


This mod cannot live with admin_tools, you have to choose only one of them.


Enable django-admin-tools to enhance the administration interface. This enables three widgets to customize certain elements. filebrowser is used, so if your project has not enabled it, you need to remove the occurrences of these widgets.


This mod cannot live with admin_style, you have to choose only one of them.


Enable django-assets to combine and minify your assets (CSS, JS). The minification library used, yuicompressor, requires the installation of Java (the OpenJDK installed by default on most Linux systems is sufficient).

In general, this component is required. If you do not intend to use it, you will need to modify the project’s default templates to remove all of its occurrences.

Assets are defined in project/ and some apps can defined their own file but our main file does not use them.

Our file is divised in three parts :

  • BASE BUNDLES: Only for app bundle like Foundation Javascript files or RoyalSlider files;
  • MAIN AVAILABLE BUNDLES: Where you defined main bundles for the frontend, use app bundles previously defined;
  • ENABLE NEEDED BUNDLE: Bundle you effectively want to use. Bundle that are not defined here will not be reachable from templates and won’t be compiled;


Enable and define customization for the CKEditor editor. It is enabled by default and used by Django CKEditor in the cms mod, and also in zinnia.

Note that DjangoCMS use it’s own app named “djangocms_text_ckeditor”, a djangocms plugin to use CKEditor (4.x).

But Zinnia (and some other generic app) use “django_ckeditor” that ship the same ckeditor but without cms addons.

This mod contains configuration for all of them.

And some useful patches/fixes :

  • the codemirror plugin that is missing from the ckeditor’s django apps;
  • A system to use the “template” plugin (see views.EditorTemplatesListView for more usage details);
  • Some overriding to have content preview and editor more near to Foundation;


Django CMS allows for the creation and management of the content pages that constitute your site’s tree structure. By default, this component enables the use of filebrowser, Django CKEditor and emencia-cms-snippet (a clone of the snippets’ plugin with a few improvements).

By default it is configured to use only one language. See its to find out how to enable the management of multiple languages.


Enable Django Codemirror to apply the editor with syntax highlighting in your forms (or other content).

It is used by the snippet’s CMS plugin.


A simple contact form that is more of a standard template than a full-blown application. You can modify it according to your requirements in its apps/contact_form/ directory. Its HTML rendering is managed by crispy_forms based on a customized layout.

By default, it uses the recaptcha mods.


Enable the use of django-crispy-forms and crispy-forms-foundation. crispy_forms is used to manage the HTML rendering of the forms in a finer and easier fashion than with the simple Django form API. crispy-forms-foundation is a supplement to implement the rendering with the structure (tags, styles, etc.) used in Foundation.


Add django-debug-toolbar to your project to insert a tab on all of your project’s HTML pages, which will allow you to track the information on each page, such as the template generation path, the query arguments received, the number of SQL queries submitted, etc.

This component can only be used in a development or integration environment and is always disabled during production.

Note that its use extends the response time of your pages and can provokes some bugs (see the warning at end) so for the time being, this mods is disabled. Enable it locally for your needs but never commit its enabled mod and remember trying to disable it when you have a strange bug.


Never enable this mod before the first database install or a syncdb, else it will result in errors about some table that don’t exist (like “django_site”).


Group together some common and various utilities from project.utils.


Add Django Filebrowser to your project so you can use a centralized interface to manage the uploaded files to be used with other components (cms, zinnia, etc.).

The version used is a special version called no grappelli that can be used outside of the django-grapelli environment.

Filebrowser manage files with a nice interface to centralize them and also manage image resizing versions (original, small, medium, etc..), you can edit these versions or add new ones in the settings.


Don’t try to use other resizing app like sorl-thumbnails or easy-thumbnails, they will not work with Image fields managed with Filebrowser.


Mod for django-filer and its DjangoCMS plugin

Only enable it for specific usage because this can painful to manage files with Filebrowser and django-filer enabled in the same project.


Enable the use of Django flatpages app in your project. Once it has been enabled, go to the in this mod to configure the map of the urls to be used.


Add django-google-tools to your project to manage the tags for Google Analytics and Google Site Verification from the site administration location.


The project is filled with a custom template project/templates/googletools/analytics_code.html to use Google Universal Analytics, remove it to return to the old Google Analytics.


Add Django PDB to your project for more precise debugging with breakpoints.

N.B. Neither django_pdb nor pdb are installed by the buildout. You must install them manually, for example with pip, in your development environment so you do not disrupt the installation of projects being integrated or in production. You must also add the required breakpoints yourself.

See the the django-pdb Readme for more usage details.


django-pdb should be put at the end of settings.INSTALLED_APPS :

“Make sure to put django_pdb after any conflicting apps in INSTALLED_APPS so that they have priority.”

So with the automatic loading system for the mods, you should enable it with a name like “zpdb”, to assure that it is loaded at the end of the loading loop.


Add Django Porticus to your project to manage file galleries.

There is a DjangoCMS plugin for Porticus, it is not enabled by default, you will have to uncomment it in the mod settings.


Enable the Django reCaptcha module to integrate a field of the captcha type via the Service reCaptcha. This integration uses a special template and CSS to make it responsive.

If you do in fact use this module, go to its mods setting file (or that of your environment) to fill in the public key and the private key to be used to transmit the data required.

By default, these keys are filled in with a fake value and the captcha’s form field therefore sends back a silent error (a message is inserted into the form without creating a Python Exception).


Enable django-sendfile that is somewhat like a helper around the X-SENDFILE headers, a technic to process some requests before let them pass to the webserver.

Commonly used to check for permissions rights to download some private files before let the webserver to process the request. So the webapp can execute some code on a request without to carry the file to download (than could be a big issue with some very big files).

django-sendfile dependancy in the buildout config is commented by default, so first you will need to uncomment its line to install it, before enabling the mod. Then you will need to create the directory to store the protected medias, because if you store them in the common media directory, they will public to everyone.

This directory must be in the project directory, then its name can defined in the PROTECTED_MEDIAS_DIRNAME mod setting, default is to use protected_medias and so you should create the project/protected_medias directory.

Your webserver need to support this technic, no matter on a recent nginx as it is allready embeded in, on Apache you will need to install the Apache module XSendfile (it should be availabe on your distribution packages) and enable it in the virtualhost config (or the global one if you want), see the Apache module documentation for more details. Then remember to update your virtualhost config with the needed directive, use the Apache config file builded from buildout.

The nginx config template allready embed a rule to manage project/protected_medias with sendfile, but it is commented by default, so you will need to uncomment it before to launch buildout again to build the nginx config file.


By default, the mod use the django-sendfile’s backend for development that is named sendfile.backends.development. For production, you will need to use the right backend for your webserver (like sendfile.backends.nginx).

Finally you will need to implement it in your code as this will require a custom view to download the file, see the django-sendfile documentation for details about this. But this is almost easy, you just need to use the sendfile.sendfile method to return the right Response within your view.


Enable a module in settings.TEMPLATE_CONTEXT_PROCESSORS to show a few variables linked to Django sites app in the context of the project views template.

Common context available variables are:

  • Current Site entry name;
  • SITE.domain: Current Site entry domain;
  • SITE.web_url: The Current Site entry domain prefixed with the http protocol like If HTTPS is enabled ‘https’ will be used instead of ‘http’;

Some projects can change this to add some other variables, you can see for them in project.utils.context_processors.get_site_metas.


This mod use the Django’s Sitemap framework to publish the sitemap.xml for various apps. The default config contains ressources for DjangoCMS, Zinnia, staticpages, contact form and Porticus but only ressource for DjangoCMS is enabled.

Uncomment ressources or add new app ressources for your needs (see the Django documentation for more details).


Enable the emencia-django-slideshows app to manage slide animations (slider, carousel, etc.). This was initially provided for Foundation Orbit and Royal Slider, but can be used with other libraries if needed.


Enable the emencia-django-socialaggregator app to manage social contents.


This app require some API key settings to be filled to work correctly.


This mod uses emencia-django-staticpages to use static pages with a direct to template process, it replace the deprecated mod prototype.


Mod for easy-thumbnails a library to help for making thumbnails on the fly (or not).

Generally this is not recommended, because by default we allready enable Filebrowser that allready ships a thumbnail system.


django-urls-map is a tiny Django app to embed a simple management command that will display the url map of your project.


Django Blog Zinnia allows for the management of a blog in your project. It is well integrated into the cms component but can also be used independently.


version 1.4.0 - 2015/04/12

  • Enforce python2.7 usage into Makefile (to avoid a bug with MacOSX);
  • Update to django==1.6.11;
  • Update to django-cms==3.0.12;
  • Enable a default robots.txt in default and integration environments so development sites won’t never be referenced;
  • Enforce to mptt==0.6.1 to avoid a but third tier apps (like django-tagging) that accept superior versions not compatible with cms;

version 1.3.8 - 2015/02/27

  • Add conf for sentry tracking in production env;
  • Fix bug into Makefile template;

Version 1.3.7 - 2015/02/26

  • Fix Makefile’s ‘install’ action so this will works on all systems (OSX included) with a shell and Python2;

Version 1.3.6 - 2015/02/25

  • Fix rst typo into README file;
  • Remove project’s apps locale dirs, close #7;
  • Fix missing django_comments in settings.INSTALLED_APPS, required by zinnia else it cause a bug on some admin views, close #9;
  • Update to djangocms==3.0.10;
  • Update to crispy-forms-foundation==0.4.1;
  • Update to djangocms-admin-style==0.2.5;

Version 1.3.5 - 2015/02/06

  • Use new options dump_other_apps and exclude_apps from emencia-recipe-drdump/drdump packages;
  • Add 2 new commands in makefile for export/import project data (database + media)

Version 1.3.4 - 2015/02/03

  • Force Python2.x usage in virtual environment from the Makefile because actually a lot of used apps can’t works with Python3 and some distributions allready use Python3 as the default Python interpreter;

Version 1.3.3 - 2015/01/29

  • Use get_civility_display into contact_form app’s email template rather civility;

Version 1.3.2 - 2015/01/28

  • Comment settings.ADMINS so we are not sending anymore Django’s mail alerts to;
  • Fix webassets bug: since we use Bundle names with version placeholder, webassets needed a manifest file to know what version to use in its templatetags. So now a webassets.manifest file is created in project/webapp_statics directory and will be copied to project/static dir when assets are deployed;

Version 1.3.1 - 2015/01/28

  • Fix a bug in project/contact_form/cms_app that was using the wrong hook name;
  • Remove sample patch for Django and unknown locales because since 1.6, Django does not care about known or unknown locale;
  • Disable ‘sitemap.xml’ mapping to a static files in the nginx config since we have a mod to generate it automatically from enabled apps;

Version 1.3.0 - 2015/01/28

  • Update to django-filer==0.9.9 to fix a bug with setuptools>=7 (this should permits soon to remove freezing to setuptools==7 and pip==1.5.x);
  • Remove “syncf5” action in Makefile because now it resides in a Makefile into foundation5’s sources;

Version 1.2.9 - 2015/01/20

Changing default behavior of Asset bundles in project/ so now bundle urls will be like /static/screen.acefe50.css instead of old behavior /static/screen.min.css?acefe50 that was causing issue with old proxies caches (see webassets documentation);

You can safely backport this change to your old projects, this should be transparent to your install and won’t require any server change.

Version 1.2.8 - 2015/01/14

  • Update to django==1.6.10;
  • Update to django-cms==3.0.9;
  • Fix default slideshow template with a bad html id;
  • Add a Makefile in foundation5 sources, move syncf5 action into it and add a syncjquery to fix compressed jquery in foundation5 vendor sources that was causing issue with compressed assets;
  • Add CMS apphook sample for contact_form;

Version 1.2.7 - 2015/01/06

  • Update to django==1.6.9;
  • Update to django-cms==3.0.7;
  • Update to Pillow==2.7.0;
  • In buildout config, remove the old patch hack to add unsupported locales from Django, since Django 1.6 does not care anymore;

Version 1.2.6 - 2014/12/26

  • Fix a damned bug with that was forcing to upgrade to setuptools=0.8 that seems to results with bad parsing on some constraints like the one from django-cms for django-mptt==0.5.2,==0.6,==0.6.1 that was causing a buildout fail on conflict version. This has been fixed with updating to the last and use its command line arguments to fix versions for zc.buildout and setuptools in the Makefile;

Version 1.2.5 - 2014/12/25

Version 1.2.4 - 2014/12/19

  • Add Foundation’s kitchen sink in a staticpage within project/templates/prototypes/foundation5.html and mounted on /prototypes/foundation5.html;
  • Add template tag library named utils_addons in project/utils/templatetags/;
  • Add split filter in utils_addons template tag library;
  • Add nginx conf for admin with timeout and max body size increase;

Version 1.2.3 - 2014/12/02

  • Improve sitemap mod, more modular and usefull;
  • Add filer and thumbnails mod, ususally not used in our projects but it could be usefull for some specific goals;
  • Fix contact_form app that was missing its file;
  • Update to crispy-forms-foundation==0.4;
  • DjangoCMS page templates has moved from project/templates/cms to project/templates/pages, following a recommandation from DjangoCMS’ documentation;
  • Add menu/menu_sidenav.html and pages/2_cols.autonav.html templates to have a template with deep menu for current root page;
  • Update to porticus==0.9.6;
  • Update to emencia-django-slideshows==0.9.4;

Version 1.2.2 - 2014/11/24

  • Add sendfile mod;
  • Add client_max_body_size sample directive usage in nginx template (but commented);
  • Add commented location /protected_medias to demonstrate sendfile mod usage within nginx template;

Version 1.2.1 - 2014/11/24

  • Update to Foundation 5.4.7;

Version 1.2 - 2014/11/19

  • Refactoring Template code to open a new way for a much modular behavior, should not break anything;

Version 1.1.3 - 2014/11/17

  • Mount 500 and 404 page view in when debug mode is activated;

Version 1.1.2 - 2014/11/16

  • Fix a bug with symlinks that was not packaged and so was missing from the installed egg, this close #1, thanks to @ilanouh;
  • Add missing gitignore rule to ignore debug_toolbar mod (it must never be installed from the start because it causes issues with cms and the syncdb command);

Version 1.1.1 - 2014/11/07

  • Update to zc.buildout==2.2.5;
  • Update to buildout.recipe.uwsgi==0.0.24;
  • Update to collective.recipe.cmd==0.9;
  • Update to collective.recipe.template==1.11;
  • Update to djangorecipe==1.10;
  • Update to porticus==0.9.5;
  • Add package cmsplugin-porticus==0.2 in buildout config;
  • Remove dependancy for zc.buildout and zc.recipe.egg;

Version 1.1 - 2014/11/03

  • Update to zc.buildout==2.2.4 to fix a bug introduced in 2.2.3;
  • Update to last script;
  • Remove Foundation3 sources, CSS and bundles, they are not used anymore;
  • Move ckeditor and minimalist CSS to common SCSS sources with Foundation5;
  • Update Compass README;
  • Correct admin_style Compass config;
  • Add ‘ar’ country to the CSS flags;
  • Recompile all CSS in project’s webapp_statics;
  • Changing to use nested bundles, so we can separate app bundles (foundation, royalslider, etc..) from the main bundles where we load the app bundles;
  • Main frontend’s CSS & JS bundles are now called main.css and main.js not anymore app.*** (yes we use the old Foundation3 ones that have been removed);

Version 1.0.4 - 2014/11/03

Update mods doc

Version 1.0.3 - 2014/11/03

Fix some app versions in version.cfg, fix app.js to use socialaggregator only if its lib is loaded.

Version 1.0.2 - 2014/11/03

Remove all enabled mods because it’s the template responsability to enabled them or not.

Version 1.0.1 - 2014/11/03

Following repository renaming for a workaround with ‘gp.vcsdevelop’.

Version 1.0 - 2014/11/03

First commit started from emencia-paste-djangocms-2 == 1.9.1 and merged with buildout_cms3 repository, bump to 1.0