Melange is a web application written in Python 2.7 that runs on Google App Engine.


You should read the text below, but if you want a quick refresher on how to get running, here's the TL;DR.


Platform / Operating System

Melange development is known to work on several versions of Debian/Ubuntu on x86_64.

  • Ubuntu 12.04 (precise)
  • Ubuntu 14.04 (trusty)
  • Debian 7.4 (wheezy)

Other OSes may or may not work without many tweaks. For best results, please use one of the above, or one closely related.


Building, testing, and running Melange depends on installation of a few system packages:

  • git
  • libxml2-dev
  • libxslt-dev
  • python (version 2.7)
  • python-dev
  • python-lxml
  • virtualenv (version 1.10 or later)
  • libpng12-dev
  • libjpeg-dev
  • libwebp-dev
  • libyaml-dev
  • xvfb
  • zlib1g-dev
  • firefox or iceweasel
  • make

This might work for you:

sudo apt-get install libxml2-dev libxslt-dev python-dev python-lxml python-virtualenv xvfb zlib1g-dev firefox make libpng12-dev libwebp-dev libjpeg-dev libyaml-dev

Setting up

If you do not yet have a melange directory set up, run the following commands.

git clone
cd soc
make setup

NOTE: There might be some errors that look like - “Bad argument -- expected name or tuple” during the documentation generation. It's a known issue in epydoc #343. The build works just fine.

Running locally

If you want to run melange locally, run the following command

make localserver

It will listen on port 8080.

Creating an AppEngine instance

If you do not already have an AppEngine instance, follow these steps, otherwise you can skip this part.

  • Go to and sign in with a Google Account
  • Click “Create an application”
  • Verify your account if prompted
  • In the “Create an Application” page, fill in an identifier (cannot be changed), you will need this later on when deploying
  • Fill in a title (can be changed later)
  • Set the “Authentication Options” on either “Open to all Google Accounts users (default)” or “Restricted to the following Google Apps domain”.
  • Hit “Create Application”

Deploying to your own instance

Assuming you have an AppEngine instance called ‘your-melange-instance’

scripts/ -o devvin -f your-melange-instance &&
thirdparty/google_appengine/ update build

Running the test suite

If you want to run the test suite, run the following


This will run, by default, all types of tests. This is the same as running

bin/run-tests -t js,pyunit

So, using -t switch it's possible to choose a list of comma-separated types of tests to run.

To run only pyunit tests:

bin/run-tests -t pyunit

To run only js tests:

bin/run-tests -t js

To run only functional tests(Headless):

bin/run-tests -t functional

To run only functional tests(In a browser):

bin/run-tests -t functional --browsers-gui

Checking Out the Code

To check out Melange source code run the following command:

Using Git repository:

git clone

Setting up your Client

Change directories into the working directory (the one created by checking out the code). Google App Engine requires a file app.yaml in the application directory. For now, you can create a dummy app.yaml file by running:

scripts/ local-devel -o devvin

Running the Code Locally

You can start the server on your computer by running:

thirdparty/google_appengine/ build

You should now be able to see the running server at http://localhost:8080/ . Congrats! You've got Melange running!

(If you want to run on a different port, you can use the --port argument. Other arguments are described here.)

(Since you are starting from scratch, you will probably want some sample data. You can use programmatically-generated sample data to save yours fingers for code. First you need to login, visit http://localhost:8080/login for the same. After login visit http://localhost:8080/seed_db to have Melange generate data for you.)

Running on and Deploying to App Engine's cluster

If you want to run an instance of Melange on Google's App Engine infrastructure, there are a few more steps to make sure it deploys the right data to the right place.

Set the application name

In app/app.yaml there's an application name that in the above steps was set to fake-application-name. After registering an application on Google App Engine, use any text editor to change the line that starts with application: fake-application-name to instead read application: <your-instance-name>. You can also run the script again:

scripts/ -o devvin -f proper-application-name 

Building With Paver

Because Tiny MCE (and possibly some other third-party content and JavaScript incorporated into Melange) is large, zipserve is used to combine this content into .zip archive files (to avoid file-count limits in Google App Engine). A side effect of this is that, for Tiny MCE to work in the textarea controls on your local working copy, launched with thirdparty/google_appengine, you still need to run a build script to produce these .zip files at least once.

To do this, you will need to execute the bin/paver script, using the following command

bin/paver build

This script will create a build/ directory at the same level as the app/ directory (and the scripts/ directory) in the hg working copy.

Deploying to Google App Engine

Once you have your application configured correctly and you have executed the paver script found in the bin folder, you are ready to deploy your Melange image to your specific Google App Engine instance.

You can run the contents of the build/ directory, in order to test what would actually be uploaded by upload to Google App Engine by using:

bin/gae_develop build

Once you are satisfied that build/ contains everything needed, you can deploy to your Google App Engine instance with:

thirdparty/google_appengine/ update build


There are a number of ways that you can contribute to the Melange project.


You must sign the Google CLA before we can accept any patches from you.

Please visit:


If you are interested in contributing to the Melange project, please join our general discussion mailing list. Also,feel free to join us on IRC.

Bug Hunting and Feature Requests

If you are (or were) a mentor or student participant in GSoC or GCI but do not have the time to contribute patches to Melange, we can still use your help. While a great deal of code is already done, some parts of the web application are not entirely bug free yet, or feature complete. Please consider writing up a feature request, or bug report. Please be precise when you file a New Issue.


Patches to the code are also welcome, even from non-committers. Please see the Gerrit page for the best way to submit patches.

The code that is used for showing pages can be found in app/soc/modules/<module_name>/views.