RapidSMS Developers Guide/Installation

The following describes how to install RapidSMS in a Virtual Machine (VM) while working on a Windows machine. This setup is suitable for both production and development.

For Linux users, simply follow inside-VM instructions or follow the regular instructions with Virtual Box.

System RequirementsEdit

Type Software Version
Operating System Ubuntu (linux) 9.10 server i386
Virtual Machine Virtualbox 3.1.4-57640-Win
SSH Client Putty 0.60
Web Browser Firefox 3.6
Editor Scite 2.03
Web Framework Django 1.1.1

Virtual Machine, Setup & ConfigurationEdit

Once all above softwares are ready, launch Virtualbox follow the Wizard:

  1. Press NEW to create a new virtual machine.
  2. Press NEXT on Welcome screen.
  3. Enter a name for your virtual machine (Ex. RapidSMS), choose Linux as an operating system type and Ubuntu as its version.
  4. Press NEXT, Choose the amount of memory you want the virtualbox to use (256M is fine).
  5. Press NEXT, Leave the Boot Hard Disk (Primary Master) checked.
  6. Press NEXT, New wizard will appear.
    1. Leave the storage type (Dynamically expanding storage )
    2. Choose the size of Storage that VirtualBox will use (8G is fine).
  7. Press Next, then Finish.

Now choose the Virtual machine you created from the above steps (RapidSMS), right-click on it and choose settings.

  1. Go Storage tab. On Storage Tree, Select the non-hard disk drive.
    1. On attribute pane, select CD/DVD Device and add the Ubuntu Server ISO you downloaded.
  2. On Network Tab:
    1. Adapter1: Check Enable Network Adapter Box.
    2. On field attached to, choose Host-only Adapter.
    3. Adapter2: check Enable Network Adapter Box
    4. On field attached to , choose Bridged Adapter
    5. On field Name, Choose the Network card on which you have internet.
  3. Close and save the settings for the VM.
  4. Now, click on File -> Preferences from the main Virtual Box Menu
    1. On Network tab, set your Adapter and ip address (ex. and network mask (Ex.
    2. On DHCP sub-tab, Disable DHCP Server.

Now start you virtual machine that you configured by clicking on START.

After Starting your Virtual machine, your operating system (in our case Ubuntu) will starts.

We'll need to install some software inside Ubuntu to configure our RapidSMS and run it properly.

Network Cards ConfigurationEdit

The above configuration set up two Network Interfaces in the VM:

  • The Host-Only one, which we'll use to access the VM at all time.
  • The bridged one, which we'll use to access Internet from the VM and expose the RapidSMS server on the network.

To configure the network in the VM, we need to edit the interfaces file:

sudo nano /etc/network/interfaces

Inside this file write the following

# The loopback network interface
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static

auto eth1
iface eth1 inet dhcp

Save the file (:x) and restart the network service:

sudo /etc/init.d/networking  restart

Python PackagesEdit

RapidSMS requires several softwares. The following command will download and install required softwares (~40MB).

 sudo apt-get install aptitude
 sudo aptitude install gettext git-core python python-pybabel python-serial \
 python-setuptools python-tz python-mysqldb python-pysqlite python python-pysqlite2 \
 sqlite sqlite3

The following command will install some additional librairies (~100MB). Optional.

 sudo aptitude install python-reportlab pdftk python-matplotlib python-xlwt

The following will install PEP8, a tool to ensure Python Coding Standards are met.

 sudo easy_install pep8

The following generates locales files in the VM. Add all the locale you might want to use for translation (you can do this after). Following are for French, English (USA) and Arabic (Jordan) in order.

 sudo locale-gen fr_FR.UTF-8
 sudo locale-gen en_US.UTF-8
 sudo locale-gen ar_JO.UTF-8

Samba Installation & ConfigurationEdit

Installing and configuring Samba will provide us a way to directly write inside-VM files from within Windows, using regular Windows Text Editors.

sudo aptitude install samba smbfs	
sudo nano /etc/samba/smb.conf

Add the following at the end of the file

Security = share
comment = RapidSMS Dev
path = /home/{your ubuntu username}
public = yes
writable = yes
create mask = 0644
directory mask = 0755
force user ={your username}
force group = {your username}

Close file and restart Samba:

sudo service samba restart

On Windows, you can now access your home folder (/home/<username>) at the following URL: \\\rsms.

You can map this folder to a Drive Letter on Windows to access it easily (works only when the VM is started).

RapidSMS DependenciesEdit

Following Code Structure, we will now create a sources folder to store all third-parties dependencies.

cd ~
mkdir sources

Django Web FrameworkEdit

After extracting the Django 1.1.1 archive (see download link under System Requirements), copy Django-1.1.1 folder to sources.

Then, change to that directory and install it

cd ~/sources/Django-1.1.1
sudo python ./setup.py install

RapidSMS Core LibraryEdit

RapidSMS main fork (core) is located at github.com/rapidsms/rapidsms.

Clone the code and install it:

cd ~/sources
git clone git://github.com/rapidsms/rapidsms.git
cd rapidsms
sudo python ./setup.py install

Now, RapidSMS is installed.

Other Third Party ApplicationsEdit

Numerous RapidSMS applications are not located into the core. There are available from their developers's repositories.

In case you want to use some, clone those repositories in sources folder then link the applications as explained in Personal Repository

Code Structure · Personal Repository