Getting Started with CommCare HQ 0.9

Getting Started with CommCare HQ 0.9

Setting up a Development Environment

The following steps guide you through setting up your development environment for CommCare HQ.

Dependencies

(Ubuntu users, refer to the package names listed at the bottom of this document)

• Git
• Python (>= 2.5, but < 3)
• MySQLdb http://sourceforge.net/projects/mysql-python/ (note that if you are using python 2.6 on windows you need to use this version: http://www.technicalbard.com/files/MySQL-python-1.2.2.win32-py2.6.exe )
• In order to register xforms you’ll need to have Java 6+ installed.
  • In Ubuntu (and other systems running apt-get) run sudo apt-get install sun-java6-jre
  • If you’re using OS X, you may have a lower version of Java set as default, which will cause “Broken Pipe” errors. To fix this, go to Applications > Utilities > Java Preferences and drag “Java SE 6” to the top of the list under “Java Application”
• Django:http://www.djangoproject.com/. Use Django 2.X.
  • Django doesn’t support two things, which we need, so we’ve added.
  • Django doesn’t support swahili translations, so we’ve added this to django/contrib/local/sw
  • Django doesn’t support permissions on models with names longer than 50 characters. We’ve extended this to 200, in django/contrib/auth/models.py.

• pytz http://pytz.sourceforge.net/
• lxml http://pypi.python.org/pypi/lxml/2.2.2
• PIL (Python Imaging Library) http://www.pythonware.com/products/pil/
• Django ImageKit http://bitbucket.org/jdriscoll/django-imagekit/wiki/Home
• Spider Oak’s zipstream for zipped up jad/jar/xform files from our build manager.
• django-digest is helping us with digest authentication (http://bitbucket.org/akoha/django-digest/wiki/Home). you’ll also need python-digest and decorator (linked from django-digest). You’ll also need mocker if you want to run unit tests.

• ‘curl’ is a useful command-line tool for development and debugging http://curl.haxx.se/download.html

Setup

• run git clone git://github.com/dimagi/commcare-hq.git
• check out the correct, 0.9 version: git checkout -b commcarehq_0.9 ;
• get the rapidsms source: cd commcare-hq ; git submodule init ; git submodule update

• copy /commcare-hq/rapidsms.ini to local.ini. This is the most up to date, and will now be your local settings for running HQ. If you don’t have access to our server, you can use Sample ini File, last updated May 4, 2010. Be sure to go through and change everything marked ‘changeme’ and update ‘/usr/local/commcarehq_dev/’ to point to your actual installation directory. You might also want to put things currently shoved in ‘/tmp/’ someplace more permanent, but that’s up to you.
• In the database block of the ini file set the mysql preferences you want and the connection information.
• In mysql, make a new database with the name you set in the local.ini. Django can create tables, but is unalbe to make databases

Running the code

First you must sync the database. This will make all the tables needed by HQ and also bootstrap some initial configuration which includes some default users and sites configuration. From the command line, navigate to the project root/commcare-hq/ directory and run the following command:

1. python manage.py syncdb

To run the server run the following command in the same directory:

2. python manage.py runserver

After running these command,you can access the apps form your browser by http://127.0.0.1:8000
or one can specify the ip address and port number like python manage.py runserver 192.168.30.8:8000

That’s it!

If you have any issues with the above, try checking the Troubleshooting page for common problems, or ask questions to our google group.

Working with the code in eclipse

To work with the Eclipse development environment, you’ll need to install:

• Eclipse
• !PyDev plugin for Eclipse: http://pydev.org/

• Go to the preferences/properties in Eclipse to set the pyDev python executable. It should be pretty self explanatory/automagical to find the right python interpreter. For compatability sake, we set the compile version to 2.5.
• You will create a single project for all of the HQ code. Create a new project. Uncheck the “use default” button and browse to your git repostitory’s commcare-hq root folder. Pick a python interpreter and uncheck the “create default src/” button as well. Create the project.
  • You should now see your project with subfolders apps/, contrib/, data/, rapidsms/ etc.
• Update the python path to point it at the root source folders you need. Go to your project properties and under python path add the following entries to your PYTHONPATH. This is to tell pydev how to do code completion and refactoring linkages.
  • /commcare-hq/apps
  • /commcare-hq/rapidsms/apps
  • /commcare-hq/rapidsms/lib

Ubuntu Users

apt-get install these packages:
python-lxml
python-setuptools
apache2
libapache2-mod-wsgi

python-dev
build-essential
python-MySQLdb
memcached
python-memcached
git-core

easy_install these (after python-setuptools is installed)

django #will install django 1.1
python-memcached
pytz

Security

If you want to be able to sign jars, you’ll need to get a KeyStore, username, and password
then set local.ini’s [releasemanager] key_store to point to the absolute location of that keystore.