Installing django CMS by hand

Installing django CMS by hand

This is how to install django CMS ‘the hard way’ (it’s not really that hard, but there is an easier way).

It’s suitable if you want to dive in to integrating django CMS into an existing project, are already experienced at setting up Django projects or indeed like to do things the hard way.

If you prefer an easier way using an automated configuration tool - definitely recommended for new users - see Installing django CMS, which is part of a complete introductory tutorial.

This document assumes you are familiar with Python and Django. After you’ve integrated django CMS into your project, you should be able to follow the Tutorials.

Requirements

Python 2.7, 3.3, 3.4 or 3.5.
Django 1.8.x, 1.9.x
django-classy-tags 0.7.0 or higher
django-treebeard 4.0
django-sekizai 0.8.2 or higher
djangocms-admin-style 1.0 or higher
An installed and working instance of one of the databases listed in the Databases section.

Note

When installing the django CMS using pip, all of the dependencies will be installed automatically.

Installing

Installing in a virtualenv using pip

Installing inside a virtualenv is the preferred way to install any Django installation.

sudo pip install --upgrade virtualenv
virtualenv env

Note

If you are not using a system-wide install of Python (such as with Homebrew), omit the usage of sudo when installing via pip.

Switch to the virtualenv at the command line by typing:

source env/bin/activate

Next, install the CMS:

pip install django-cms

This will automatically install all of the requirements listed above.

While you could install packages one at a time using pip, we recommend using a requirements.txt file. The following is an example file that can be used with pip to install django CMS and its dependencies:

# Bare minimum
django-cms>=3.0
# These dependencies are brought in by django CMS, but if you want to
# lock-in their version, specify them
Django>=1.8
django-treebeard==3.0
django-sekizai==0.8.2
django-classy-tags==0.6.2
djangocms-admin-style==0.2.2
six==1.3.0
# Optional, recommended packages
Pillow>=2
django-filer==0.9.9
cmsplugin-filer==0.10.1
django-reversion==1.8.5

Note

In the above list, packages are pinned to specific version as an example; those are not mandatory versions; refer to requirements for any version-specific restrictions.

If you are using PostgreSQL as your database, add the Python adaptor to your requirements file:

psycopg2

For MySQL you would instead add:

mysql-python

Note

While the django CMS is compatible with Python 3.3+, the mysql-python package is not.

Before you install the Python adaptors for your chosen database, you will need to first install the appropriate headers and development libraries. See the platform specific notes below.

Installing on Ubuntu

If you’re using Ubuntu (tested with 14.04), the following should get you started:

sudo aptitude install python-pip
sudo pip install virtualenv

Next, install the appropriate libraries to build the Python adaptors for your selected database. For PostgreSQL:

sudo aptitude install libpq-dev postgresql-client-9.3 python-dev

For MySQL:

sudo aptitude install libmysqlclient-dev python-dev

Installing and configuring database servers are beyond the scope of this document. See Databases below for more information and related links.

Installing on Mac OSX

If you are using the system provided Python (2.7 or later), ensure you have pip installed.

sudo easy_install pip
sudo pip install virtualenv

If you’re using Homebrew you can install pip and virtualenv with the python generic package:

brew install python
pip install virtualenv

Next, install the appropriate libraries to build the Python adaptors for your selected database. For PostgreSQL:

brew install postgres

For MySQL:

brew install mysql

Note

Homebrew does not set the databases to run automatically. The software necessary for the Python adaptors will be installed but if you wish to run the database server locally, follow the Homebrew instructions shown in the terminal output after installing.

Databases

We recommend using PostgreSQL or MySQL with django CMS. Installing and maintaining database systems is outside the scope of this documentation, but is very well documented on the systems’ respective websites.

To use django CMS efficiently, we recommend:

Creating a separate set of credentials for the django CMS project.
Creating a new database for the django CMS project, not reusing an existing one.

Configuration and setup

Preparing the environment

The following steps assume your Django project will be - or already is - in ~/workspace/myproject, and that you’ll be using a virtualenv.

If you already have a virtualenv with a project in it, activate it and move on to Configuring your project for django CMS.

Otherwise:

cd ~/workspace/myproject/
virtualenv env
source env/bin/activate
pip install -r requirements.txt

Create a new Django project

django-admin.py startproject myproject

If this is new to you, you ought to read the official Django tutorial, which covers starting a new project.

Configuring your project for django CMS

Open the settings.py file in your project.

To make your life easier, add the following at the top of the file:

# -*- coding: utf-8 -*-
import os
gettext = lambda s: s
BASE_DIR = os.path.dirname(os.path.dirname(__file__))

Add the following apps to your INSTALLED_APPS. This includes django CMS itself as well as its dependencies and other highly recommended applications/libraries:

'cms',  # django CMS itself
'treebeard',  # utilities for implementing a tree
'menus',  # helper for model independent hierarchical website navigation
'sekizai',  # for JavaScript and CSS management
'djangocms_admin_style',  # for the admin skin. You **must** add 'djangocms_admin_style' in the list **before** 'django.contrib.admin'.
'django.contrib.messages',  # to enable messages framework (see :ref:`Enable messages <enable-messages>`)

Also add any (or all) of the following plugins, depending on your needs (see the note in The INSTALLED_APPS setting about ordering):

'djangocms_file',
'djangocms_googlemap',
'djangocms_inherit',
'djangocms_picture',
'djangocms_teaser',
'djangocms_video',
'djangocms_link',
'djangocms_snippet',

Note

Most of the above plugins were previously distributed with django CMS, however, most of them are now located in their own repositories and renamed. Furthermore plugins: 'cms.plugins.text' and 'cms.plugins.twitter' have been removed from the django CMS bundle. Read 3.0 release notes for detailed information.

Warning

Adding the 'djangocms_snippet' plugin is a potential security hazard. For more information, refer to snippet_plugin.

Some commonly-used plugins are described in more detail in Some commonly-used plugins. There are even more plugins available on the django CMS extensions page.

In addition, make sure you uncomment (enable) 'django.contrib.admin'

You may also wish to use django-filer and its components with the django CMS plugin instead of the djangocms_file, djangocms_picture, djangocms_teaser and djangocms_video core plugins. In this case you should check the django-filer documentation and django CMS plugin documentation for detailed installation information, and then return to this tutorial.

If you opt for the core plugins you should take care that directory to which the CMS_PAGE_MEDIA_PATH setting points (by default cms_page_media/ relative to MEDIA_ROOT) is writeable by the user under which Django will be running. If you have opted for django-filer there is a similar requirement for its configuration.

If you want versioning of your content you should also install django-reversion and add it to INSTALLED_APPS:

'reversion'

You need to add the django CMS middlewares to your MIDDLEWARE_CLASSES at the right position:

MIDDLEWARE_CLASSES = (
    'cms.middleware.utils.ApphookReloadMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.common.CommonMiddleware',
    'cms.middleware.user.CurrentUserMiddleware',
    'cms.middleware.page.CurrentPageMiddleware',
    'cms.middleware.toolbar.ToolbarMiddleware',
    'cms.middleware.language.LanguageCookieMiddleware',
)

Notice that django CMS v3.2 introduces a new middleware: cms.middleware.utils.ApphookReloadMiddleware. This should be placed very near the top of your middleware classes tuple/list.

Note

In Django 1.8, the TEMPLATE_DIRS, TEMPLATE_LOADERS and TEMPLATE_CONTEXT_PROCESSORS settings are rolled into the TEMPLATES setting.

For earlier versions, put the context_processors and items listed into TEMPLATE_CONTEXT_PROCESSORS, the DIRS items into TEMPLATE_DIRS and so on.

 TEMPLATES = [
     {
         'DIRS': [os.path.join(BASE_DIR, "templates"),],
         'OPTIONS': {
             'context_processors': [
                 # ...
                 'sekizai.context_processors.sekizai',
                 'cms.context_processors.cms_settings',
                 ],
             },
         },
     ]

Warning

Be sure to have 'django.contrib.sites' in INSTALLED_APPS and set SITE_ID parameter in your settings: they may be missing from the settings file generated by django-admin depending on your Django version and project template.

Changed in version 3.0.0.

Warning

Django messages framework is now required for the toolbar to work properly.

To enable it you must be check the following settings:

INSTALLED_APPS: must contain 'django.contrib.messages'
MIDDLEWARE_CLASSES: must contain 'django.contrib.messages.middleware.MessageMiddleware'
TEMPLATES["OPTIONS"]["context_processors"]: must contain 'django.contrib.messages.context_processors.messages'

Point your STATIC_ROOT to where the static files should live (that is, your images, CSS files, JavaScript files, etc.):

STATIC_ROOT = os.path.join(BASE_DIR, "static")
STATIC_URL = "/static/"

For uploaded files, you will need to set up the MEDIA_ROOT setting:

MEDIA_ROOT = os.path.join(BASE_DIR, "media")
MEDIA_URL = "/media/"

Note

Please make sure both the static and media sub-folders exist in your project and are writeable.

Add at least one template to CMS_TEMPLATES; for example:

CMS_TEMPLATES = (
    ('template_1.html', 'Template One'),
    ('template_2.html', 'Template Two'),
)

We will create the actual template files at a later step, don’t worry about it for now. Simply paste this code into your settings file.

Note

The templates you define in CMS_TEMPLATES have to exist at runtime and contain at least one {% placeholder <name> %} template tag to be useful for django CMS.

The django CMS allows you to edit all languages for which Django has built in translations. Since these are numerous, we’ll limit it to English for now:

LANGUAGES = [
    ('en', 'English'),
]

Finally, set up the DATABASES part of the file to reflect your database deployment. If you just want to try out things locally, SQLite3 is the easiest database to set up, however it should not be used in production. If you still wish to use it for now, this is what your DATABASES setting should look like:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'database.sqlite'),
    }
}

django CMS, as well as its plugins, supports both Django 1.7 and Django 1.6 migrations.

URL configuration

You need to include the 'cms.urls' urlpatterns at the end of your urlpatterns. We suggest starting with the following ~/workspace/myproject/myproject/urls.py:

from django.conf import settings
from django.conf.urls import include, url
from django.conf.urls.i18n import i18n_patterns
from django.conf.urls.static import static
from django.contrib import admin
urlpatterns = i18n_patterns('',
    url(r'^admin/', include(admin.site.urls)),
    url(r'^', include('cms.urls')),
) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Creating templates

django CMS uses templates to define how a page should look and what parts of it are editable. Editable areas are called placeholders. These templates are standard Django templates and you may use them as described in the official documentation.

Templates you wish to use on your pages must be declared in the CMS_TEMPLATES setting:

CMS_TEMPLATES = (
    ('template_1.html', 'Template One'),
    ('template_2.html', 'Template Two'),
)

If you have followed this tutorial from the beginning, this code should already be in your settings file.

Now, on with the actual template files!

Fire up your favourite editor and create a file called base.html in a folder called templates in your myproject directory.

Here is a simple example for a base template called base.html:

{% load cms_tags sekizai_tags %}
<html>
  <head>
      <title>{% page_attribute "page_title" %}</title>
      {% render_block "css" %}
  </head>
  <body>
      {% cms_toolbar %}
      {% placeholder base_content %}
      {% block base_content %}{% endblock %}
      {% render_block "js" %}
  </body>
</html>

Now, create a file called template_1.html in the same directory. This will use your base template, and add extra content to it:

{% extends "base.html" %}
{% load cms_tags %}
{% block base_content %}
  {% placeholder template_1_content %}
{% endblock %}

When you set template_1.html as a template on a page you will get two placeholders to put plugins in. One is template_1_content from the page template template_1.html and another is base_content from the extended base.html.

When working with a lot of placeholders, make sure to give descriptive names to your placeholders so you can identify them more easily in the admin panel.

Now, feel free to experiment and make a template_2.html file! If you don’t feel creative, just copy template_1 and name the second placeholder something like “template_2_content”.

Static files handling with sekizai

The django CMS handles media files (CSS stylesheets and JavaScript files) required by CMS plugins using django-sekizai. This requires you to define at least two sekizai namespaces in your templates: js and css. You can do so using the render_block template tag from the sekizai_tags template tag library. We highly recommended putting the {% render_block "css" %} tag as the last thing before the closing </head> HTML tag and the {% render_block "js" %} tag as the last thing before the closing </body> HTML tag.

Initial database setup

django CMS uses Django’s built-in support for database migrations to manage creating and altering database tables.

Fresh install

Run:

python manage.py migrate
python manage.py createsuperuser

Upgrade

If you are upgrading your installation of django CMS from a previous version run:

python manage.py migrate

Check you did everything right

Now, use the following command to check if you did everything correctly:

python manage.py cms check

Up and running!

That should be it. Restart your development server using python manage.py runserver and point a web browser to 127.0.0.1:8000 : you should get the django CMS “Installation Successful” screen.

Use the new side-frame-based administration by appending ‘?edit’ to your URL as follows: http://127.0.0.1:8000/?edit. This will reveal a login form.

If this is your first django CMS project, read through the tutorial for a walk-through of the main features of django CMS.

For more information on using django CMS for managing web content, see Using django CMS.

To deploy your django CMS project on a production web server, please refer to the Django documentation.

Installing django CMS by hand

Installing django CMS by hand

Requirements

Recommended

Text Editors

Other Plugins

File and image handling

Revision management

Installing

Installing in a virtualenv using pip

Installing on Ubuntu

Installing on Mac OSX

Databases

Configuration and setup

Preparing the environment

Create a new Django project

Configuring your project for django CMS

URL configuration

Creating templates

Static files handling with sekizai

Initial database setup

Fresh install

Upgrade

Check you did everything right

Up and running!