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.