RapidPro is an open-source software product that allows us to visually build the workflow logic for running mobile-based services. This software includes features for managing users’ contacts dynamically, graphically analyzing the data our service receives, connecting to multiple communication channels (i.e., SMS, voice, USSD, and social media), sending messages in multiple languages, and inter-operating with external systems. The RapidPro software can be set up and hosted as a service on local servers or on the cloud.

RapidPro is the collaboration child of UNICEF and Nyaruka, a Rwandan software firm. Nyaruka built it with their experience in developing mobile-based solutions. RapidPro has been developed and branded for UNICEF to host and build its own services and applications internally and together with its partners.

Anyone trying to install RapidPro in their machine may find the task daunting at first. Hence, in this post, we will take a step-by-step approach to set up RapidPro. We will start from the very beginning and steadily go through all the requirements to make the process as easy as possible. So, let’s get started!

Setting up RapidPro – Prerequisites

This is a guide on setting up RapidPro in the local machine for development purposes. However, we need to understand that RapidPro requires many modules to work. Hence, we start by setting up all the prerequisites before we can install RapidPro.

In this post, we follow the instructions as tested on Ubuntu 20.04; directions require modification when using Windows.

The following prerequisites are needed to get started:

  • Python 3.9 or later
  • PostgreSQL 9.6 or later, along with the PostGIS extensions
  • Redis 3.2 or later installed and listening on localhost
  • NPM which handles the JS dependencies

Setting up Python

Ubuntu 20.04 comes with Python 3.8 preinstalled. However, with the latest versions moving to Python 3.9, we need to update our python version to 3.9. So, first, we need to update our packages:

$ sudo apt update

Upgrade the packages:

$ sudo apt -y upgrade

Check the python version:

$ python3 -V


Python 3.8.10

In order to install python 3.9, we need to add the deadsnakes PPA to our system sources list:

$ sudo apt install software-properties-common

$ sudo add-apt-repository ppa:deadsnakes/ppa

A prompt will pop up; we press [Enter] to continue. Once the repository is added successfully, we install python 3.9 using:

$ sudo apt install python3.9

This will install python 3.9, and we can check the version and verify:

$ python3.9 --version

Additionally, we install pip to manage/install software packages for python:

$ sudo apt install -y python3-pip

We have now successfully installed python 3.9 on our local machine.

Install PostgreSQL

Now that we have taken care of setting up python, we have to think about our database. RapidPro connects to the postgresql database. Hence, we have to install postgresql and the contrib package using the following commands:

$ sudo apt install postgresql postgresql-contrib

The contrib package adds additional utilities and functionality.

Additionally, we need to install the PostGIS extension for postgresql:

$ sudo apt install postgis

Our postgresql database is now ready to go!

Install Redis

On our previous step, we have set up our database. In this step, we install Redis-server that acts as a database, cache, and message broker for our database.

$ sudo apt-get install redis-server

Redis-server will start running every time the server boots.

We can check the version of the redis-server using the following command:

$ redis-server --version

Here are some useful commands to know when using Redis:

sudo service redis-server start # start redis-server

sudo service redis-server stop # stop redis-server

sudo service redis-server restart # restart the redis-server

Create Database and Username

So far, we have installed python, postgresql database, and redis-server on our machine. Thus, it is time we create the username and database that our RapidPro instance will use.

RapidPro requires username temba with password temba.

To create the username and password, first, we enter the postgresql bash:

$ sudo -i -u postgres

Now we can create user temba with password temba:

[email protected]:~$ createuser temba --pwprompt –d

Enter password for new role: (enter temba)

Enter it again: (enter temba)

Once we complete creating the username, we can move forward and create the database:

$ createdb temba

At this point, we need to connect as a superuser that can install the PostGIS extensions.

$ psql

postgres=# \c temba

You are now connected to database "temba" as user "postgres".

temba=# create extension postgis;


temba=# create extension postgis_topology;


temba=# create extension hstore;


temba=# create extension "uuid-ossp";


We have completed all the prerequisites. We can now exit the database:

temba=# \q

To log out of postgresql, we can simply use the exit command.

[email protected]:~$ exit

We can also log out using ctrl + d.

Clone/Download RapidPro

Now that all the prerequisites are installed, we are ready to set up RapidPro. The first step is to install git so that we are able to clone the RapidPro repository from Github:

$ sudo apt install git

Github repository: RapidPro

Clone the repository into the local machine:

$ git clone --depth 1 --branch <tag_name> <repo_url>

The <tag_name> is the tag of the RapidPro version we want to download. So, the above command will look like this with the tag_name and the repo_url in place: git clone –depth 1 –branch v6.4.8 https://github.com/rapidpro/rapidpro.git

We can always check the latest stable release tag from RapidPro’s Github page.

Once we finish cloning, our RapidPro directory will be ready. Next, we go to the project folder and create a symbolic link from the settings.py.dev file.

$ cd rapidpro/temba

$ ln -s settings.py.dev settings.py

$ cd ..

A good practice is to check the current directory using command pwd to have an exact idea of where we are all the time.

Build the virtual environment

It is time to build a virtual environment for our RapidPro instance. We should always use a virtual environment when setting up and running RapidPro.

$ cd rapidpro/

$ sudo apt install -y python3.9-venv

$ python3.9 -m venv env

Enter the virtual environment using:

$ source env/bin/activate

The above command activates the virtual environment. We can always get out of the virtual environment anytime using the command deactivate.

**We must carry out all the following steps inside the virtual environment.

First, we Install poetry in the environment:

$ pip install poetry

We can check the poetry version using:

$ poetry --version

We use poetry in order to install all the pinned dependencies for RapidPro with just one command:

$ poetry install

The command calls poetry to install all the required dependencies. After poetry completes its task, it is possible to run all the migrations.

$ python manage.py migrate

Installing JavaScript dependencies

We have arrived at the final item of our dependency list. Now, we have to install Node.js and NPM:

$ sudo apt install nodejs

$ sudo apt install npm

$ node -v

$ npm -v

**Note: Node version must be v10.x and above. Ubuntu 18.04 or older install an earlier version. Hence, if v10 is not installed, we should first install a suitable version of nodejs. We can ignore these steps if our node version is 10 or above.

The first step is to install NVM using wget:

$ sudo apt install wget

$ wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash

Then, we allow NVM to be used from user’s bash profile.

$ source ~/.profile

Next, we check out all the versions of Node.js available:

$ nvm ls-remote

From there, we pick and install version 10.19.0 (or the latest stable version available)

$ nvm install 10.19.0

We should make sure that the correct version is installed. Afterward, we run npm install to set up all the dependencies:

$ npm install

Once npm installs all the requirements, we have to install lessc and coffeescript globally. These are necessary because RapidPro templates and CSS files need compilation.

$ sudo npm install less -g

$ sudo npm install coffeescript -g

Starting the Django server

It is now possible to run the development server and run RapidPro on http://localhost:8000 .

$ python manage.py runserver

Congratulations! We have successfully set up a development environment for RapidPro!

We can exit/stop the Django server using ctrl + c in the terminal. Also, to exit the virtual environment, we deactivate:

$ deactivate

Installing Additional Components

RapidPro uses multiple external components to utilize its features fully. Therefore, it is a must that we install these components to use the flows and channel features of RapidPro.

Most of the components are GoLang applications. Hence, our first step is to install Go in the system. These components are meant to run continuously in the background.

Set working directory to the home/<user> location:

$ cd

Install Go

Download Go and unzip the tar.gz file. Check the GoLang website for the latest version: Go

$ wget https://go.dev/dl/go1.17.7.linux-amd64.tar.gz

$ tar -xzf go1.17.7.linux-amd64.tar.gz

The first command downloads the binaries for the Go while the second command extracts the files into the user directory.

Now we need to add the go folder directory in our .bashrc file:

$ sudo nano .bashrc

Once the file is accessed, we have to navigate to the end of the file (ctrl + shift + _ followed by ctrl + v ). Add the following details in the last lines. Save and exit.

export GOPATH=$HOME/go

export PATH=$GOPATH/bin:$GOROOT/bin:$PATH

Run the following command and check the go version:

$ source ~/.bashrc

$ go version

Note that go version must be v1.16 or higher.

Installing Go as the root user

When installing Go as the root user, we have to modify the previously mentioned instructions a bit in order to make it work. Firstly, we would have to extract the contents of the tar.gz file in the /usr/local directory:

$ tar -C /usr/local -xzf go1.17.7.linux-amd64.tar.gz

Again, same as last time, we open up the .bashrc file and the following content in the end of the file. Note that the GOROOT destination has been changed.

export GOROOT=/usr/local/go

export GOPATH=$HOME/go

export PATH=$PATH:$GOPATH/bin:$GOROOT/bin

Restart the .bashrc file and check the go version

$ source ~/.bashrc

$ go version

Install Elasticsearch

Elasticsearch is needed for mailroom, courier and rp-indexer to function. The following commands will install Elasticsearch on to the system:

$ wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.15.2-linux-x86_64.tar.gz

$ wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.15.2-linux-x86_64.tar.gz.sha512

$ shasum -a 512 -c elasticsearch-7.15.2-linux-x86_64.tar.gz.sha512 

$ tar -xzf elasticsearch-7.15.2-linux-x86_64.tar.gz

It is time to run Elasticsearch. Go to the Elasticsearch directory and run the application:

$ cd elasticsearch-7.15.2/

$ ./bin/elasticsearch

We can check if Elasticsearch is running or not by going to the localhost:9200 port.

As root user, the above-mentioned steps may not work, in which case, Debian package for Elasticsearch is needed for installation.

Import the Elasticsearch PGP Key:

$ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -

Install from the APT repository:

$ sudo apt-get install apt-transport-https

Save the repository definition to /etc/apt/sources.list.d/elastic-7.x.list:

$ echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list

Install Elasticsearch.

$ sudo apt-get update && sudo apt-get install elasticsearch

Enable Elasticsearch.

$ systemctl enable --now elasticsearch

Elasticsearch can be started and stopped as follows:

$ systemctl start elasticsearch.service

$ systemctl stop elasticsearch.service

Check Elasticsearch status:

$ curl -X GET "localhost:9200"

Install Mailroom

Mailroom is a Go application that handles flows and flow editors in RapidPro. We download the source files from the Github repository.

Github repository: Mailroom

$ git clone --depth 1 --branch <tag_name> <repo_url>

After downloading mailroom, run the following commands to build/install mailroom.

$ cd mailroom/

$ go install ./cmd/mailroom

This creates a new executable in $GOPATH/bin called mailroom . Now we can run mailroom by just using the command mailroom . We can stop Mailroom anytime using ctrl+c.

Install Courier

Courier is a Go application that handles messages, and its installation process is identical to that of mailroom. Download the stable release from the Github repository.

Github repository: Courier

$ git clone --depth 1 --branch <tag_name> <repo_url>

After downloading is completed, we run the following command to build courier:

$ cd courier/

$ go install ./cmd/courier

This creates a new executable in $GOPATH/bin called courier . Now run courier by just using the command courier . To stop Courier, we can use ctrl+c.

Install RP-Indexer

RP-Indexer is a simple Go application that takes care of creating and keeping Elasticsearch indexes up to date with changes for the contacts in RapidPro. The installation process is identical to that of mailroom and courier. Download the stable release from the Github repository.

Github repository: RP-Indexer

$ git clone --depth 1 --branch <tag_name> <repo_url>

Build the indexer:

$ cd rp-indexer/

$ go install ./cmd/rp-indexer

This creates a new executable in $GOPATH/bin called rp-indexer . Now run the indexer by just using the command rp-indexer . We can stop RP-indexer by using ctrl+c.

**NOTE: Mailroom, Courier and RP-Indexer must continuously run in the background with RapidPro. Otherwise, the previously mentioned features will not work.

Setting up the /etc/environment variables

We can always check the respective repositories of all the components (mailroom, courier and rp-indexer) for /etc/environment variables that needs to be set accordingly. Open up /etc/environments:

$ sudo nano /etc/environments

We must add the following lines to the /etc/environments . This should be enough to run everything in the development server. Add them to /etc/environments:

MAILROOM_DB="postgres://temba:[email protected]/temba?sslmode=disable"
INDEXER_DB="postgres://temba:[email protected]/temba?sslmode=disable"


At this point, we have successfully installed RapidPro and all of its components in our development server!

We are now ready to start working with RapidPro and utilize its capabilities as we best see fit. All the instructions are up to date at the time of writing this article. As with any guide, however, the technology in question will always evolve with time. Thus, we may need to modify some of the steps mentioned in this guide accordingly in the future.

More information regarding RapidPro, its community forums, and hosting requirements is available here.

This page was last edited on 7 April 2022, at 8:44 am