Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

229 lines (150 sloc) 6.282 kb


This page describes the manual installation procedure. If you can, you should set up the :doc:`vagrant-managed virtual machine <installation-vagrant>` instead.


To run everything and make all the tests pass locally, you'll need the following things (in addition to Git, of course).

  • Python 2.6.
  • setuptools or pip.
  • MySQL Server and client headers.
  • Memcached Server and libmemcached.
  • Elasticsearch 0.90.9.
  • RabbitMQ.
  • libxml and headers.
  • libxslt and headers.
  • libjpeg and headers.
  • zlib and headers.
  • libmagic and headers.
  • libtidy and headers
  • Several Python packages. See Installing the Packages.

Installation for these is very system dependent. Using a package manager, like yum, aptitude, or brew, is encouraged.

Additional Requirements

If you want to use Apache, instead of the dev server (not strictly required but it's more like our production environment) you'll also need:

  • Apache HTTPD Server.
  • mod_wsgi

See the documentation on :doc:`WSGI <wsgi>` for more information and instructions.

Getting the Source

First, to follow the instructions from Webdev Bootcamp, fork the project into your own account. Then get the source using:

mkdir mdn # you probably want to do this, since you'll have to create
cd mdn    # product_details_json/ as a sibling of kuma/ later.
git clone<your_username>/kuma.git
cd kuma
git submodule update --init --recursive

Installing the Packages

Compiled Packages

There are a small number of compiled packages, including the MySQL Python client. You can install these using pip (if you don't have pip, you can get it with easy_install pip) or via a package manager. To use pip, you only need to do this:

sudo pip install -r requirements/compiled.txt

Python Packages

All of the pure-Python requirements are available in a git repository, known as a vendor library. This allows them to be available on the Python path without needing to be installed in the system, allowing multiple versions for multiple projects simultaneously.


Start by creating a file named, and putting this line in it:

from settings import *

Now you can copy and modify any settings from into and the value will override the default.


At a minimum, you will need to define a database connection. An example configuration is:

    'default': {
        'NAME': 'kuma',
        'ENGINE': 'django.db.backends.mysql',
        'HOST': 'localhost',
        'USER': 'kuma',
        'PASSWORD': '',
        'OPTIONS': {'init_command': 'SET storage_engine=InnoDB'},
        'TEST_CHARSET': 'utf8',
        'TEST_COLLATION': 'utf8_unicode_ci',

Note the two settings TEST_CHARSET and TEST_COLLATION. Without these, the test suite will use MySQL's (moronic) defaults when creating the test database (see below) and lots of tests will fail. Hundreds.

Once you've set up the database, you can generate the schema with Django's syncdb command:

mkdir ../product_details_json
./ syncdb
./ migrate

This will generate an empty database, which will get you started!

Initializing Mozilla Product Details

One of the packages Kuma uses, Django Mozilla Product Details, needs to fetch JSON files containing historical Firefox version data and write them within its package directory. To set this up, just run:

./ update_product_details do the initial fetch.


If you want to see images and have the pages formatted with CSS you need to set your with the following:

DEBUG = True

Setting DEBUG = False will put the installation in production mode and ask for minified assets. In that case, you will need to generate CSS from stylus and compress resource:

./ compress_assets

Configure Persona

Add the following to so that Persona works with the development instance:

SITE_URL = 'http://localhost:8000'
PROTOCOL = 'http://'
DOMAIN = 'localhost'
PORT = 8000
SESSION_COOKIE_SECURE = False # needed if the server is running on http://

The SESSION_EXPIRE_AT_BROWSER_CLOSE setting is not strictly necessary, but it's convenient for development.

Secure Cookies

To prevent error messages like Forbidden (CSRF cookie not set.):, you need to set your with the following:


Testing it Out

To start the dev server, run ./ runserver, then open up http://localhost:8000. If everything's working, you should see the MDN home page!

You might need to first set LC_CTYPE if you're on Mac OS X until bug 754728 is fixed:

export LC_CTYPE=en_US

What’s next?

See :doc:`development <development>` for further instructions.

Some site funcationaly require waffle flags. Waffle flags include:

  • kumaediting: Allows creation, editing, and translating of documents
  • page_move: Allows moving of documents
  • revision-dashboard-newusers: Allows searching of new users through the revision dashboard
  • events_map: Allows display of map on the events page
  • elasticsearch: Enables elastic search for site search

To create or modify waffle flags, visit "/admin/" and click the "Waffle" link.

Last Steps

See the :doc:`search documentation <elasticsearch>` for steps to get Elasticsearch search working.

Jump to Line
Something went wrong with that request. Please try again.