- Setting up RapidPro - Prerequisites
- Setting Up Python
- Install PostgreSQL
- Install Redis
- Create Database and Username
- Clone/Download RapidPro
- Build the virtual environment
- Installing JavaScript dependencies
- Starting the Django server
- Installing Additional Components
- Install Go
- Installing Go as the root user
- Install Elasticsearch
- Install Mailroom
- Install Courier
- Install RP-Indexer
- Setting up the /etc/environment variables
- Conclusion
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
Output
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:
postgres@server:~$ 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;
CREATE EXTENSION
temba=# create extension postgis_topology;
CREATE EXTENSION
temba=# create extension hstore;
CREATE EXTENSION
temba=# create extension "uuid-ossp";
CREATE EXTENSION
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.
postgres@server:~$ 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 0.0.0.0:8000
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:temba@localhost/temba?sslmode=disable"
INDEXER_DB="postgres://temba:temba@localhost/temba?sslmode=disable"
INDEXER_ELASTIC_URL="http://localhost:9200"
Conclusion
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 16 October 2023, at 12:54 pm
How can we help you?
























Thanks for this tutorial, I managed to install rapidpro but, I can’t send messages and receive messages using telegram channel, is there some step missing? Thanks.
Thank for you querry. We will see the issue. If there is any, we may update the guide. Please stay with us.
Dead pent subject material, appreciate it for information.
Thank you so much!