We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Install And Get Started With Django-Based Mezzanine CMS on Ubuntu

Posted Feb 25, 2014 33.4k views Django Ubuntu


A content management system (CMS) is an application that aims to help people with publishing contents of various types online ... at least that's what they're supposed to do. With ever-so-popular and growing demand, most CMS applications have reached a point where they are even harder to use than crafting your own solution based on a framework.

Fortunately, there are a handful of brilliant exceptions to this rule – Mezzanine CMS is one of them.

Built on top of the powerful (and expandable) Django web framework, Mezzanine offers web-developers and online publishing enthusiasts alike a truly smooth ride from the very beginning with its extremely intuitive way of building websites.

In this DigitalOcean article, we are going to see how to prepare a brand new Ubuntu 13 cloud server to install and deploy a Mezzanine CMS based web-site from the absolute scratch. Continuing, we will see how to get started with this elegant library as we publish our first piece of content.


1. Django In Brief

2. Mezzanine CMS

  1. Features
  2. Third-Party Support
  3. Complete Application Modules

3. Getting Started: Preparing Your Ubuntu Droplet

4. Installing Mezzanine

  1. Python Virtual Environment For Mezzanine
  2. Install Mezzanine And Dependencies

5. Working With Mezzanine

  1. Create A Project
  2. Initiate The Database
  3. Basic Configurations
  4. Test The Application
  5. Create Your First Content

6. Getting Ready For Production

7. Summary

Django In Brief

Django is a Python programming language based web-development framework. Being an extremely large project and library, it packs and ships tons of tools and features to developers who are looking forward to getting started quickly. If you are willing to spend a significant amount of time to "learn" a framework in order to save some in the future, Django for Python is probably the go-to solution.

Given their nature, powerful frameworks are not only helpful for creating custom applications or APIs but also packaged software, aiming to solve a specific set of problems. One of these custom software built on top of Django is the Mezzanine CMS.

Mezzanine CMS

Mezzanine - as we have mentioned - is a content management system built on top of the popular web-development framework Django. Although it requires some knowledge of Python programming language and a certain level of familiarity with Django, getting started using Mezzanine to create a web-site is much simpler than other content management tools and libraries, especially those based on other languages.


As a CMS, Mezzanine comes with a great amount of useful functionality that covers a majority of common needs that web-developers expect to get from such applications. Since Django is so easily expandable, Mezzanine is also surrounded with many additional third-party packages that can help you with shaping your web-site anyway you like as well. In fact, Mezzanine itself is an extension, or a Django application.

Here are some popular features of the Mezzanine CMS:

  • Scheduled publishing;

  • Drag-and-Drop (DaD) page ordering;

  • Theming via themes marketplace;

  • Account management and e-mail verification;

  • Easy social content sharing;

  • Mobile (e.g. smartphone, tablet etc.) friendly theming;

  • Spam filtering;

  • URL shortening;

  • Disqus and Gravatar integration;

  • Automated deployments;

  • Built-in blogging engine;

  • Visual content editing;

  • Tagging;

  • Customising individual content types and their styles;

  • Easy migrations;

and much more.

Third-Party Support

Benefiting from expansion capabilities of Django, Mezzanine currently supports plenty of additional libraries and modules which aim to help developers with their various needs.

Some of these popular third-party modules are:

  • mdown:

    Widgets and filters to create and publish content using Markdown.

  • Themes:

    Theme collection for Django (thus Mezzanine).

  • Captcha:

    Automatic captcha support for Mezzanine form builder.

  • Slides:

    Responsive slide display.

  • Calendar:

    Calendar implementation for Mezzanine.

  • Podcasts:

    Podcasts manager.

  • Pageimages:

    Easily adding individual background-images for Mezzanine pages.

  • Twittertopic:

    Helps to manage twitter topics.

  • Recipes:

    Recipe publishing plug-in.

Complete Application Modules

Some Mezzanine modules allows the creation of complete web-application with unique features, such as an e-commerce web-site.

Some of these popular customisation modules are:

  • Cartridge:

    An online-shopping / e-commerce module.

  • Bookmarks:

    A multi-user bookmarking application.

  • Polls:

    A polling application.

  • Careers:

    A job posting application.

  • Wiki:

    A wiki solution.

Getting Started: Preparing Your Ubuntu VPS

Mezzanine is a Python project and you need to tune your system correctly in order to set up and run your web-site without glitches or errors.

If you haven't got your droplet ready for this yet, head over quickly to our Ubuntu/Python article:

And continue with the Mezzanine installation instructions found below.

Installing Mezzanine

We are going to make use of the brilliant Python tool virtualenv in order to install and contain Mezzanine and its dependencies. Therefore, in this section, we are going to start with creating an environment.

Python Virtual Environment For Mezzanine

If you haven't already, create a virtual environment:

virtualenv mezzanine_env
cd         mezzanine_env

Or activate it:

source bin/activate

Install Mezzanine And Dependencies

Once we have our environment ready, we can use pip package manager to get Mezzanine and all the dependencies installed.

Run the following command to install Mezzanine using pip:

pip install mezzanine

You may also need to install pillow

pip install pillow

Working With Mezzanine

Being a Django based tool, Mezzanine comes with Django-like features. One such item shipped with Mezzanine is mezzanine-project which is used for administrative tasks.

Let's get started working with Mezzanine.

Create A Project

Creating a new web-site with Mezzanine is as easy as running a single command:

# Usage: mezzanine-project [project name]
# Example:
mezzanine-project mezzanine_app

# Enter the application directory:
cd mezzanine_app

Initiate The Database

Mezzanine brings some additions to Django's standard manage.py management tool, such as the created instructions.

Run the following to create and initiate a sample database:

python manage.py createdb

Once you execute this command, you will be asked a series of questions:

# You just installed Django's auth system,
# which means you don't have any superusers defined.
# Would you like to create one now? (yes/no):
# ^^ Create an admin account by answering the questions.

# Please enter the domain and optional port in
# the format 'domain:port'.
# For example 'localhost:8000' or 'www.example.com'. 
# Hit enter to use the default (
# ^^ Enter your domain name.

# Would you like to install some initial demo pages?
# Eg: About us, Contact form, Gallery. (yes/no): 
# ^^ Create sample data.

After having answered these questions, it is time to check out the application.

Basic Configurations

In order to avoid errors and do things the right way, although not strictly necessary, we need to perform certain configurations.

Let's edit the settings.py file using the nano text editor:

nano settings.py

Scroll down the file and find ALLOWED_HOSTS, i.e.:


Replace it with:

# ALLOWED_HOSTS = []                # comment out
# Example (From Django documentation):
    '.example.com',  # Allow domain and subdomains
    '.example.com.', # Also allow FQDN and subdomains

# Replace example.com with your own domain name.

Afterwards, go right below the block of comments and find:


And replace it with your own, e.g.:

TIME_ZONE = 'Europe/Amsterdam'

Save and exit by pressing CTRL+X and confirming with Y.

Test The Application

Run the following command to run a sample application server to check out your brand new Mezzanine application:

python manage.py runserver

You can check out your installation by visiting your droplet on port 8000:

http://[your droplet's IP]:8000

Note: To terminate the test server, press CTRL+C.

Create Your First Content

Let's publish some new content and see how easy it is to use Mezzanine.

Visit the admin section by going to:

http://[your droplet's IP]:8000/admin

Login with admin credentials you have set and press "Log In".

You will see the Dashboard. From here, you can either publish a quick blogpost, or hover your cursor over the Content drop-down menu and choose any item you wish to edit, e.g.:

  • Pages:
    http://[your droplet's IP]:8000/admin/pages/page/

Getting Ready For Production

When you are finished creating your Mezzanine project, you should try to avoid relying on the testing server the application comes with.

For deployments, a fully-fledged web-application server (e.g. Unicorn) must be used, preferably behind a reverse-proxy that will handle the initial processing of requests and distribution of static files, such as images.

To get a quick overall idea of how to go to production, check out the section titles "Getting Ready For Production"on our article: How To Prepare Ubuntu Cloud Servers For Python Web-Applications.


If you have already been through this article once, or simply prefer a quick summary of installation instructions to get you started, check below:

# Preare the system and install Python tools:
aptitude    update
aptitude -y upgrade
aptitude install -y build-essential
aptitude install -y cvs subversion git-core mercurial
aptitude install python-setuptools python-dev python2.7-dev python-software-properties libpq-dev
aptitude install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev
curl https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py | python -
curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python -
export PATH="/usr/local/bin:$PATH"
pip install virtualenv

# Create a virtual environment:
virtualenv mezzanine_env
cd mezzanine_env    
source bin/activate
pip install mezzanine

# Create a Mezzanine project:
mezzanine-project mezzanine_app
cd mezzanine_app
python manage.py createdb --noinput

# Run the testing server:
python manage.py runserver

Note: The last command created using the --noinput flag will allow you to initiate the database without being asked questions. Your admin username will be admin, and your password default. From hereon, you continue with configuring and testing.

Submitted by: O.S. Tezer


Creative Commons License