ScaleConf Workshop - Getting Set Up

Note

These instructions were written for the first Vumi workshop on the 21st of April 2013, right after the ScaleConf conference in Cape Town.

Spotted an error? Please feel free to contribute to the documentation.

Installation

If you’re feeling particularly brave you can by all means set up Vumi from scratch on your local machine by cloning the GitHub repository and installing all the necessary packages.

However we would strongly recommend you use the VirtualBox image that’s been ready made for the workshop in combination with Vagrant. It has all of the necessary dependencies already installed for you on an Ubuntu Precise machine image.

Using Vagrant & VirtualBox

Ensure you have the latest versions of both Vagrant and VirtualBox installed before starting.

To add and start the vumi dev box do the following:

$ git clone git://github.com/praekelt/vumi.git
$ cd vumi
$ vagrant box add vumi ~/path/to/the/vumi-dev.box
$ vagrant up

When this completes you’ll have a virtual machine running Ubuntu Precise 64 with the Vumi repository mounted at /var/praekelt/vumi

Log in to your machine with:

$ vagrant ssh

Setting up your Transport

Now things will only get interesting once you can start interacting with them via your phone. Let’s get the SMS and USSD transports set up:

$ cd /var/praekelt/vumi/
$ virtualenv ve
$ source ve/bin/activate
$ pip install -r requirements.pip

Grab a coffee while you’re waiting for this to complete, it can take a while.

You should by now have received your username, password and tokens for https://go.vumi.org/ which you are going to federate with. This will allow you to receive USSD traffic right on your machine.

Complete the config file below with the details provided and save it in a file called ussd_transport.yaml:

transport_name: ussd_transport
account_key: <your account key>
access_token: <your acccess token>
conversation_key: <your conversation key>

middleware:
    - logging_mw: vumi.middleware.logging.LoggingMiddleware

logging_mw:
    log_level: debug

Next save the following bit in a file called supervisord.conf in the etc folder:

[unix_http_server]
file=/tmp/supervisor-vumi.sock   ; (the path to the socket file)

[supervisord]
logfile=./logs/supervisord.log ; (main log file;default $CWD/supervisord.log)
logfile_maxbytes=50MB       ; (max main logfile bytes b4 rotation;default 50MB)
logfile_backups=10          ; (num of main logfile rotation backups;default 10)
loglevel=info               ; (log level;default info; others: debug,warn,trace)
pidfile=./tmp/pids/supervisord.pid ; (supervisord pidfile;default supervisord.pid)
nodaemon=false              ; (start in foreground if true;default false)
minfds=1024                 ; (min. avail startup file descriptors;default 1024)
minprocs=200                ; (min. avail process descriptors;default 200)

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

[supervisorctl]
serverurl=unix:///tmp/supervisor-vumi.sock ; use an http:// url to specify an inet socket

[program:ussd_transport]
command=twistd -n
    --pidfile=./tmp/pids/%(program_name)s.pid
    vumi_worker
    --worker-class=vumi.transports.vumi_bridge.GoConversationTransport
    --config=./ussd_transport.yaml
stdout_logfile=./logs/%(program_name)s_%(process_num)s.log
stderr_logfile=./logs/%(program_name)s_%(process_num)s.err

[program:hangman]
command=twistd -n
    --pidfile=./tmp/pids/%(program_name)s.pid
    vumi_worker
    --worker-class=vumi.demos.hangman.HangmanWorker
    --set-option=worker_name:hangman_worker
    --set-option=transport_name:ussd_transport
    --set-option=random_word_url:http://randomword.setgetgo.com/get.php
stdout_logfile=./logs/%(program_name)s_%(process_num)s.log
stderr_logfile=./logs/%(program_name)s_%(process_num)s.err

When that’s done we can start things up:

$ supervisord -c etc/supervisord.conf
$ supervisorctl -c etc/supervisord.conf tail -f ussd_transport

Now dial the number that’s associated with your conversation and you will be prompted with a game of hangman running from your local machine.

Writing Applications

In the next section we’ll be getting into application development, starting with Python and later moving on to Javascript.