Skip to content
This repository

Open source lifestream and stats web app

README.rst

Causal 1.0 readme

1. Intro

Firstly causal and its developers are not associated with any of the services we integrate with.

All integration is done using publicly available APIs. Where extra permission is required we ask the logged in user to provide us/causal with permission to access their data using the API supplied by the service owner.

WE DO NOT STORE ANY DATA FROM THE THIRD PARTY EXCEPT OAUTH TOKENS
We only store the oauth details, causal doesn't store any updates from the third party. Causal does cache

pages locally, these only survive as long as the caching server is running (e.g. memcached.)

It was deliberate choice not to store any data to avoid any potential privacy issues.

That said causal will store usernames and oauth permissions in the database. Causal uses the least amounts of permissions required to get data from a third party. That said not every service has fine grained permissions so please be aware that the oauth tokens should not be shared.

2. Design

We have broken each service we integrate with in a Django application. Each service can enabled from local_settings.py like so:

INSTALLED_SERVICES = (
  'causal.twitter',
  'causal.foursquare',
  #'causal.flickr',
  #'causal.facebook',
  #'causal.github',
  #'causal.lastfm',
  #'causal.googlereader',
)
# Lines beginning with # are commented out and so are not enabled

This enables only Foursqaure and Twitter services for the user to integrate with.

3. Run Modes

Causal can be run as multi user service by enabling user registration in local.settings.py as so:

ENABLE_REGISTRATION = True

This will allow users to register with the site user the django-registration app. This will email the user after sign up with a link to validate their email address.

If multi user access isnt required as for example you wish to run you own causal instance just for your updates set ENABLE_REGISTRATION = False to disable user registration. You will then need to register a user by hand in the admin interface, locate at http://HOSTNAME/_ca-admin That is the default address of the admin interface.

4. Build/Install

Causal can be configured using the setup.py installer, buildout, or via easy_install or pip. As well as buildout, you can install Causal and it's dependencies within a virtualenv using either of setup.py or pip.

4.1 Download

If you're installing with setup.py, buildout or installing from source within a virtualenv, you can grab the source 1 of 2 ways:

Checkout our development HEAD from Github, via git:

git clone git://github.com/causality/causal.git

Download our development HEAD as a tar:

curl -L -C - -O https://github.com/causality/causal/tarball/master
tar xzf causality-causal-*.tar.gz
mv causality-causal-*/ causal/

Or download a stable tagged release as a tar:

curl -L -C - -O https://github.com/causality/causal/tarball/master
tar xzf causality-causal-*.tar.gz
mv causality-causal-*/ causal/

4.2 setup.py

To install from the setuputils/distutils installer:

### git clone the source, or curl and untar here ###
cd causal
python setup.py install

This unfortunately doesn't install all the dependencies for the core services, you would need to install these seperately, as listed in extras_requirements.txt.

4.3 easy_install/pip

To install from PyPi using easy_install:

easy_install causal

and core-services:

easy_install causal[core-services]

Using pip:

pip install causal

pip unfortunately has the same restriction regards installing extras like core-services that setup.py does, so you would need to install the requirements seperately (see below).

4.4 buildout

To build a sandboxed Django environment containing Causal using buildout:

### git clone the source, or curl and untar here ###
cd causal
./configure
python buildout_bootstrap.py
bin/buildout

After which you should have a set of endpoints in bin/, e.g.:

cd src/causal
cp local_settings.py.example local_settings.py
## At this point you'll probably want to open local_settings.py and customise the settings ##
bin/django syncdb
bin/django migrate
bin/django createsuperuser
bin/django runserver

4.5 Bootstrapping a virtualenv

To quickly bootstrap a virtualenv for development (or even deployment), we recommend using the virtualenv_wrapper and pip tools:

mkvirtualenv causal
### git clone the source, or curl and untar here ###
cd causal
cd virtualenv_build
# This will use pip to install the dependancies for causal AND it's core-services
# as well as adding any source directories to your virtualenv's PYTHONPATH
./bootstrap.py
cd ../src/causal
cp local_settings.py.example local_settings.py
## At this point you'll probably want to open local_settings.py and customise the settings ##
./manage.py syncdb
./manage.py migrate
./manage.py createsuperuser
./manage.py runserver

4.6 Requirements

  • Django >= 1.2
  • oauth2
  • south >= 0.7
  • django-registration == 0.7
  • django-timezones == 0.2.dev2
  • python-dateutil < 2.0
  • pytz

The following allow the different services to be interacted with:

  • BeautifulSoup - Required to parse data back from github.com
  • feedparser >= 4.0 - Required for general rss parsing - google.com/reader
  • flickrapi - Required to talk to flickr.com
  • github2 - Required to talk to github.com
  • tweepy - Required to talk to twitter.com
  • twitter-text-py - Required to parse data back from twitter.com
  • pyfacegraph - Required for facebook.com

5. Accessing Services

After enabling a service the user will be prompted either for a username for the basic services and oauth for restrictive ones.

5.1 Sharing

The service is shared using the sliders on the settings page. Once a service is shared its available as a json feed:

http://HOSTNAME/USERNAME.json

Where USERNAME is the username of the user.

5.2 Stats

The front page contains links to stats about each service.

5.3 Enabling a service

Add the service into INSTALLED_APPS in your local_settings.py.

The following services will requirement some API authentication details too:

  • causal.twitter - OAuth consumer key and consumer secret.
  • causal.facebook - OAuth2 consumer key and consumer secret.
  • causal.foursquare - OAuth consumer key and consumer secret.
  • causal.flickr - API key.
  • causal.lastfm - API key.

Please see the API websites for the relevant service to find out how to get this details.

local_settings.py.example has an example of the SERVICE_CONFIG dict that these values should go in.

The service is then ready to roll.

6. Upcoming

We had our own ideas of where we wanted to lead the project but we decided its the users who know best. With this in mind we are open to suggestions for improvements and feature requests. Email us at team@causal.com or find the current ticket list at: http://github.com/causality/causal/issues

The project is hosted at http://github.com/causality/causal please fork away!

7. Hacking

7.1 Adding more services

A service is django app. Create a basic app. The are a few key this to note.

7.1.1 urls.py

  • / - callback called by the third party usually on oauth callback
  • /auth - called when the user enables the service this typically sends the user off to the third party
  • /stats - adds a link on the home page

7.1.2 service.py

get_items

This is the key method that fetches the data and returns data in json for the interface to render.

meh

Something went wrong with that request. Please try again.