• Prerequisites
• Checking Out the Code
• Setting up your Client
• Running the Code Locally
• Running on and Deploying to App Engine's cluster
• Contributing
• Troubleshooting

Prerequisites

Melange is a web application written in python 2.5 (install) that runs on Google App Engine. For more setup information, take a look at CodingHintsAndTips.

Checking Out the Code

We are in the middle of switching repositories (from SVN to Mercurial/hg). So please be advised that currently we will try to keep SVN repository in sync with Mercurial, however in the long run we will only use our Mercurial repository.

To check out Melange source code run the following command:

Using Mercurial repository (suggested!):

hg clone http://soc.googlecode.com/hg/ melange

Using SVN repository:

svn checkout http://soc.googlecode.com/svn/trunk/ melange

Using SVN repository with git (this is a development mirror, but you should be fine using it):

git clone git://repo.or.cz/Melange.git melange-git

On Windows, you can use TortoiseSVN to do the checkout from http://soc.googlecode.com/svn/trunk/ SVN repository or you can use TortoiseHg to do the checkout from http://soc.googlecode.com/hg/ Mercurial repository.

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/gen_app_yaml.py fake-application-name

Running the Code Locally

You can start the server on your computer by running:

thirdparty/google_appengine/dev_appserver.py app

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. Visit http://localhost:8080/seed_db to have Melange generate data for you and save your fingers for code!)

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>

Building With scripts/build.sh

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 build.sh script found in the scripts folder. On a UNIX system, in the trunk/ directory of the working copy, using shell commands, this can be done with something like:

cd scripts/
./build.sh

This script will create a build/ directory at the same level as the app/ directory (and the scripts/ directory) in the svn working copy. If you are using Windows, you will need to have Cygwin, and have it on your path before system binaries as the Windows find command conflicts with the bash find command. You'll also need to explicitly prefix with bash unless you have set up an association between sh and bash.

Deploying to Google App Engine

Once you have your application configured correctly and you have executed the build.sh script found in the scripts 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 appcfg.py upload to Google App Engine by using:

thirdparty/google_appengine/dev_appserver.py build

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

thirdparty/google_appengine/appcfg.py update build

Contributing

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

Discussion

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 GHOP 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

Patches to the code are also welcome, even from non-committers.

Troubleshooting

AppConfigNotFoundError

soc-read-only$ thirdparty/google_appengine/dev_appserver.py app
Traceback (most recent call last):
  File "soc-read-only/thirdparty/google_appengine/google/appengine/tools/dev_appserver.py", line 2638, in LoadAppConfig
    raise AppConfigNotFoundError
google.appengine.tools.dev_appserver.AppConfigNotFoundError

This error means that it can not find a app.yaml file. Please check the following things,

• You are running the command in the directory you checked out.
• You have created the app.yaml from app.yaml.template in step Running the Code.

Socket.error

File "/usr/lib/python2.5/BaseHTTPServer.py", line 101, in server_bind
    SocketServer.TCPServer.server_bind(self)
  File "/usr/lib/python2.5/SocketServer.py", line 341, in server_bind
    self.socket.bind(self.server_address)
  File "<string>", line 1, in bind
socket.error: (98, 'Address already in use')

This error means that some other program is running on port 8080 (the default port that appengine starts on). This can also happen if you try and run two copies of the program at once.

To run the program on a different port use the --port argument, for example

thirdparty/google_appengine/dev_appserver.py --port=9999 build

You will then need to connect to the correct port when browsing to the site. IE In the above example you would need to go to http://localhost:9999/.

BadValueError

File "/google_appengine/google/appengine/ext/db/__init__.py" in filter
  1482.       raise BadValueError('Filtering on lists is not supported')

Exception Type: BadValueError at /
Exception Value: Filtering on lists is not supported

This error means you are running a version of AppEngine that does not support the IN operator, please use the version of appengine that ships with Melange under /thirdparty/google_appengine, or update to a recent enough version (that is, >= 1.1.9).

<type 'exceptions.ImportError'>

Google App Engine SDK currently runs only on Python 2.5. If your system provides Python 2.6 or later as the default version of Python, you are likely to get the following warning as soon as you start the SDK by running

thirdparty/google_appengine/dev_appserver.py build

thirdparty/google_appengine/google/appengine/tools/appcfg.py:40: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  import sha
INFO     2009-04-29 19:49:06,517 appengine_rpc.py] Server: appengine.google.com
INFO     2009-04-29 19:49:06,529 appcfg.py] Checking for updates to the SDK.
thirdparty/google_appengine/google/appengine/api/datastore_types.py:555: DeprecationWarning: object.__init__() takes no parameters
  super(Email, self).__init__(self, email)
thirdparty/google_appengine/google/appengine/api/datastore_types.py:745: DeprecationWarning: object.__init__() takes no parameters
  super(PhoneNumber, self).__init__(self, phone)
thirdparty/google_appengine/google/appengine/api/datastore_types.py:532: DeprecationWarning: object.__init__() takes no parameters
  super(Link, self).__init__(self, link)

And when you try to access a page using any URL, you get this exception

  File "thirdparty/google_appengine/google/appengine/tools/dev_appserver.py", line 996, in decorate
    return func(self, *args, **kwargs)
  File "thirdparty/google_appengine/google/appengine/tools/dev_appserver.py", line 1444, in LoadModuleRestricted
    description)
  File "/usr/lib/python2.6/multiprocessing/__init__.py", line 83, in <module>
    import _multiprocessing
ImportError: No module named _multiprocessing

The workaround for this is to install Python 2.5 on your machine. It will be then be accessible by using python2.5 on the command line. Then open thirdparty/google_appengine/dev_appserver.py in your favorite text editor and replace the first line,

#!/usr/bin/env python

with

#!/usr/bin/env python2.5

Save the changes in the file, close it and restart the GAE development server.

Depending on the operating system (Mac OS X, different linux distributions) you just might be able to create symbolic link python for python2.5 file that way you don't have to modify dev_appserver.py file.

<class 'django.core.exceptions.ImproperlyConfigured'>

Error importing middleware app_profiler.app_profiler: "No module named pstats"
args = ('Error importing middleware app_profiler.app_profiler: "No module named pstats"',)
message = 'Error importing middleware app_profiler.app_profiler: "No module named pstats"'

This error means you're missing pstats Python module. It happens at least on Ubuntu Jaunty. This module is part of python-profiler package. So to install it you can open a console and write:

sudo apt-get install python-profiler