| #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 == | |
| Building, testing, and running Melange depends on installation of a few system packages: | |
| * git | |
| * libxml2-dev | |
| * libxslt-dev | |
| * openjdk-7-jdk | |
| * python (version 2.7) | |
| * python-dev | |
| * python-lxml | |
| * virtualenv (version 1.10 or later) | |
| * xvfb | |
| == 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 | |
| virtualenv venv | |
| venv/bin/pip install -U lxml setuptools | |
| venv/bin/python bootstrap.py | |
| bin/buildout | |
| bin/gen-app-yaml local-devel | |
| bin/paver build | |
| }}} | |
| == 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 Melange generated 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 generated 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. |