RapidSMS Developers Guide/Personal Repository

As mentioned in Code Structure, our main place of work will be a new folder.

Start by creating this folder:

cd ~
mkdir sms

This folder will need to follow some guidance. It will be your RapidSMS home. From now, unless specified, we always consider to be inside this folder and it will be called your repository.

local.ini file

local.ini file is the main rapidsms configuration file. It includes rapidsms-specific config, apps-specific config and backend-specific config. It is actually overwriting the default rapidsms.ini file from the core.

The Django configuration is not directly accessible as it is stored inside rapidsms core.

Create a file named local.ini and add the following content:

[rapidsms]
    apps=logger,admin,webapp,ajax,httptester,echo
    backends=http

[log]
    level=debug
    file=/tmp/rapidsms.log

[database]
    engine=sqlite3
    name=rapidsms.db

[http]
    host=localhost
    port=1338

[httptester]
    host=localhost
    port=1338

the required [sections] are rapidsms and database. apps= is a comma separated list of all the rapidsms apps you want to use. The above list will allow you to test the system via the web interface. backends= is a comma separated list of the backends to start. A backend is a module that handles incoming/outgoing message. Most popular is gsm backend (also called pygsm) which sends/receives messages via a physically connected GSM modem. In the above example, we use the http backend which allows you to fake the behavior of a modem to test incoming/outgoing message.

In RapidSMS, you can configure apps (and backends) from the local.ini file by creating a section for it.

The [http] section configures the http backend. the [httptester] section configures the httptester app. Use the same host and port for both httptester and http for the HTTP Tester App to work.

apps folder

RapidSMS expects an apps folder inside.

mkdir apps

__init__.py

Since both your repository are included in PYTHON_PATH, they are considered Python modules. You thus need to create an empty __init__.py file inside both to mark them as modules.

touch __init__.py
touch apps/__init__.py''

manage.py / rapidsms script

Every Django app includes a manage.py script which gives access to Django-related operations: creating database, etc. RapidSMS requires a modified version of that script to launch the router.

Create a file named rapidsms with the following content:

#!/usr/bin/env python
# vim: ai ts=4 sts=4 et sw=4 encoding=utf-8

import sys, os
from os import path

# figure out where all the extra libs (rapidsms and contribs) are
libs=[os.path.abspath('lib'),os.path.abspath('apps')] # main 'rapidsms/lib'
try:
    for f in os.listdir('contrib'):
        pkg = path.join('contrib',f)
        if path.isdir(pkg) and \
                'lib' in os.listdir(pkg):
            libs.append(path.abspath(path.join(pkg,'lib')))
except:
    # could be several reasons:
    # no 'contrib' dir, 'contrib' not a dir
    # 'contrib' not readable, in any case
    # ignore and leave 'libs' as just
    # 'rapidsms/lib'
    pass

# add extra libs to the python sys path
sys.path.extend(libs)

# import manager now that the path is correct
from rapidsms import manager

if __name__ == "__main__":
    manager.start(sys.argv)

Make sure it has execution rights.

chmod +x ./rapidsms

Linking third-parties apps

In local.ini file, we requested several apps to be started. RapidSMS expects those apps to be located in your apps/ subfolder, just like any regular app.

Create symlinks as follow to include them in your repository:

cd apps
ln –s  /home/user_name/sources/rapidsms/apps/admin
ln –s  /home/user_name/sources/rapidsms/apps/ajax
ln –s  /home/user_name/sources/rapidsms/apps/locations
ln –s  /home/user_name/sources/rapidsms/apps/logger
ln –s  /home/user_name/sources/rapidsms/apps/patterns
ln –s  /home/user_name/sources/rapidsms/apps/reporters
ln –s  /home/user_name/sources/rapidsms/apps/webapp

Database

RapidSMS, like Django is database driven.

Creating the database

From the local.ini file, you specified database connection information. There, just like with Django, you can select different engines (MySQL, SQLite, etc).

Once configured, use the syncdb command of the rapidsms script:

./rapidsms syncdb

This command will create the database schema of all the apps named in local.ini, according to the Django/Models convention. If this command fails with a message about a parser error, modify your local.ini files so that you remove the leading spaces/tabs in the lines that start without a bracket.