#summary How to get started with Melange
#labels Featured,Phase-Guidelines,Contents-Draft,Importance-Featured

<wiki:toc max_depth="1" />

= Prerequisites =

[MelangeIntro Melange] is a web application written in Python 2.7 that runs on
[http://code.google.com/appengine/ Google App Engine].

= TL;DR = 

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

== Prerequisites == 

=== 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.
 
=== Packages ===

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 http://code.google.com/p/soc/
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 [https://sourceforge.net/p/epydoc/bugs/363/ #343]. The build works just fine.

== Running locally ==

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

{{{
thirdparty/google_appengine/dev_appserver.py build
}}}

== Creating an !AppEngine instance ==

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

 * Go to http://www.appspot.com 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/gen_app_yaml.py -o devvin -f your-melange-instance &&
thirdparty/google_appengine/appcfg.py update build
}}}


== Running the test suite ==

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

{{{
bin/run-tests
}}}

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 http://code.google.com/p/soc/
}}}

= 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 local-devel -o devvin
}}}

= Running the Code Locally =
You can start the server on your computer by running:

{{{
thirdparty/google_appengine/dev_appserver.py 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 [http://code.google.com/appengine/docs/thedevwebserver.html 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/gen_app_yaml.py -o devvin -f proper-application-name 
}}}

== Building With Paver ==

Because
[http://code.google.com/p/soc/source/browse/#svn/trunk/app/tiny_mce Tiny MCE]
(and possibly some other third-party content and JavaScript incorporated
into Melange) is large,
[http://code.google.com/p/googleappengine/source/browse/#svn/trunk/google/appengine/ext/zipserve 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 <tt>.zip</tt> 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 `appcfg.py 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/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
[MailingListsGuidelines#General_discussion_list general discussion mailing list].
Also,feel free to join us [IrcChannelGuidelines 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 [http://tinyurl.com/new-issue New Issue].

== Patches ==

[ContributionReviews#Patches Patches] to the code are also welcome,
[ContributionReviews#Suggested_patches_from_casual_contributors even from non-committers].

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