README.txt

http://cardstories.org/

Copyright (C) 2010,2011 Xavier Antoviaque <xavier@antoviaque.org> (gameplay and specifications)
Copyright (C) 2010,2011 David Blanchard <david@blanchard.name> (gameplay and specifications)
Copyright (C) 2010,2011 tartarugafeliz <contact@tartarugafeliz.com> (artwork)
Copyright (C) 2011 Loic Dachary <loic@dachary.org> (software)

  A player (who we will call the author) creates a new game. 
  He chooses a card, picks a word or a sentence to describe it
  and invites players to participate.
  Each players is given seven cards and are required to pick
  one that best matches the author's sentence.
  Once enough players have chosen a card, the author displays all chosen
  cards and the players try to figure out which one is the author's.
  The author wins if at least one of the players guesses right, but not all
  of them do. The winners are the author and the players who guessed right. 
  If the author loses, all the other players win. 


####################################
Setting up a development environment
####################################

The following are instructions to set up a contained development environment
on a recent installation of Ubuntu or Debian.

First, install the following packages.

    $ sudo apt-get install postfix python-twisted python-lxml \
      python-httplib2 python-pip sqlite3

[Optional] Create a virtual environment for Card Stories, to avoid
dependencies conflict with other software installed on your system:

    $ mkvirtualenv cardstories

Now install the remaining python dependencies with pip:

    $ pip install -r requirements.txt

Now, make sure you are at the root of the cardstories checkout.  At this point,
create the default database structure for the website, but first, create a
local configuration file containing the following:

$ vim website/local_settings.py
-------------------
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': '/tmp/website.sqlite',
        'USER': '',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}
DEFAULT_FROM_EMAIL='Card Stories <feedback@farsides.com>'
BASE_URL='http://local.cardstories.org:8000'
-------------------

Now, create the database:

$ website/manage.py syncdb
$ website/manage.py migrate

Note that for local Facebook development, you must also add an entry to
/etc/hosts that matches the domain name in your Django site configuration.  It
is recommended when running the above syncdb command to chose
"local.cardstories.org" as the domain name, and then to add a line in
/etc/hosts like the following:

127.0.0.1 local.cardstories.org

If for any reason you need to run the website dev server on a different host or
port, these files that must be modified accordingly (and the cardstories web
service restarted if it's already running):

   * tests/djangoauth/djangoauth.xml
   * tests/mail/mail.xml

Create the log folder: 

    $ mkdir log/

On one terminal window, run the cardstories web service.  Under default
configuration, the following command assumes you have postfix configured
properly for relaying emails sent to 'localhost' (otherwise invitations won't
be sent out):

$ PYTHONPATH=.:etc/cardstories twistd --nodaemon cardstories \
	--static $(pwd)/static --port 5000 --interface 0.0.0.0 \
	--db /tmp/cardstories.sqlite \
	--plugins-dir plugins \
	--plugins-libdir /tmp \
	--plugins-logdir log/ \
	--plugins-confdir tests \
	--plugins 'djangoauth chat activity table mail' \
	--plugins-pre-process 'djangoauth chat'
	--plugins-post-process 'table'

On a second terminal window, still from the root of the checkout, run the
website development server, which by default binds to localhost and port 8000.
However, for local Facebook redirection to work (which you set up above in
/etc/hosts), you must run the server on port 80 as root:

$ sudo website/manage.py runserver 0.0.0.0:80

Now simply access http://local.cardstories.org/, and code away!


###########################
Enabling Open Web Analytics
###########################

To use OWA, first you must get it up and running somewhere.  To do so, follow
the installation steps here:

http://wiki.openwebanalytics.com/index.php?title=Installation

Once it's configured and running, for example at http://localhost:8080/, log in
and obtain your Site ID.  With this information in hand, start by setting the
correct values in website/settings.py:

$ vim website/settings.py
----------
OWA_ENABLE = True
OWA_URL = 'http://localhost:8080/'
OWA_SITE_ID = '<your_site_id>'
----------

Once this is done, all relevant page views should be logged.  Game state
changes will be artificially logged as page views with URLs in the following
format, where <skin_name> refers to an existing skin in the game.

http://local.cardstories.org/?skin=<skin_name>

You can then proceed to set up goals in OWA accordingly.


#################################
Deploying cardstories with Apache
#################################

In order to deploy cardstories with Apache, the following additional packages
must be installed:

$ sudo apt-get install apache2 libapache2-mod-wsgi

From the root of your cardstories checkout, install cardstories to the default
locations with:

$ sudo python setup.py install

Then, from cardstories root, copy the apache configuration file to the proper
location on the file system, and enable it.  You may need to edit it depending
on your site characteristics (particularly the location of django's admin
media):

$ sudo cp website/apache/apache2.conf /etc/apache2/sites-available/cardstories
$ sudo a2ensite cardstories

Now enable the required apache mods, and restart the server:

$ a2enmod wsgi
$ a2enmod proxy_http
$ sudo /etc/init.d/apache2 restart

Don't forget to create the default database for the website and run the
cardstories web service as described in the previous section.

Finally, to future deployments, you can create a separate local_settings.py
containing just the stuff you want applied locally (such as Facebook app id,
OWA url, etc) in:

/usr/share/cardstories/website/local_settings.py

To disable specific email notifications, after deployment edit
/etc/cardstories/plugins/mail/mail.xml so that it contains only the "allow"
nodes you need (valid options are 'invite', 'pick', 'voting', 'vote',
'complete'):

<mail ...>
  <allow>invite</allow>
  <allow>vote</allow>
</mail>

If NO notifications are to be sent, create an empty allow node (for backward
compatibility, if there aren't any allow nodes, mail will be sent for all
events):

<mail ...>
  <allow></allow>
</mail>


##############
Usage examples
##############

To display the cardstories web service usage information:

$ PYTHONPATH=.:etc/cardstories twistd cardstories --help

To run the webservice without mail or djangoauth:

$ PYTHONPATH=.:etc/cardstories twistd --nodaemon cardstories \
	--static $(pwd)/static --port 5000 --interface 0.0.0.0 \
	--db /tmp/cardstories.sqlite \
	--plugins-dir plugins \
	--plugins-libdir /tmp \
	--plugins-confdir tests \
	--plugins-logdir log \
	--plugins 'auth chat' \
	--plugins-pre-process 'auth chat activity' \

To check if the webservice replies, run the following (requires curl). The
following must return the [{"games": [], "type": "tabs", "modified": 0}, {"type": "players_info}"]
string:

$ curl --silent 'http://localhost:5000/resource?action=state&type=tabs=player_id=0'


#############
Extra plugins
#############

* Bot plugin:
    - See ./plugins/bot/README.txt for installation instructions


#################
Running the tests
#################

First install the dependencies:

$ sudo apt-get install python-coverage jscoverage

Running the Python tests (Twisted and Django):

$ make -f maintain.mk clean
$ make -f maintain.mk check

Running the Javascript tests - using your browser, go to:

- http://local.cardstories.org:8000/static/test/index.html
- http://local.cardstories.org:8000/static/test/audio.html
- http://local.cardstories.org:8000/static/test/chat.html
- http://local.cardstories.org:8000/static/test/owa.html
- http://local.cardstories.org:8000/static/test/table.html
- http://local.cardstories.org:8000/static/test/tabs.html


######################
Packaging instructions
######################

To create a source distribution use:

$ v=2.0.0 ; python setup.py sdist --dist-dir .. ; mv ../cardstories-$v.tar.gz ../cardstories_$v.orig.tar.gz

To create the Debian GNU/Linux package use:

$ dpkg-buildpackage -S -uc -us


##########
Migrations
##########

A) Upgrading the webservice DB
==============================

When upgrading, if there has been alteration to the webservice database schema, 
migration files will be added to the migrations/ folder. Just run them, in numerical 
order, using a command like:

    $ sqlite3 /tmp/cardstories.org.sqlite < migrations/001_add_tabs_table.sql


B) Upgrading Django's DB (v2.2+)
================================

You will also need to make sure there hasn't been any DB alteration in django - run
the following commands to ensure you're up to date:

    $ ./website/manage.py syncdb
    $ ./website/manage.py migrate

B') Upgrading Django's DB (from before v2.2)
============================================

Prior to version 2.2, django wasn't using south to handle migrations. So if you have 
a database from before 2.2, run the following commands to avoid having south trying
to recreate the database from scratch (if you ran syncdb on the 2.1 version, make 
sure you drop the cardstories_usercard table, as the migration will attempt to 
create it)

    $ ./website/manage.py syncdb
    $ ./website/manage.py migrate cardstories 0001 --fake


B) Developers - Automatically generating Django migrations
==========================================================

For the webservice, you will have to create the SQL migration files manually in the
migrations/ folder, but for django south will take care of it automatically for you,
based on alterations you make to the models.py file. Simply run the following
command:

    $ ./website/manage.py schemamigration cardstories --auto 
    $ ./website/manage.py migrate cardstories


######################
Additional information
######################

As of Apr, 26th 2011 there are 321 LOC of JavaScript, 687 LOC of Python = 1008 LOC
As of Jun, 19th 2011 there are 473 LOC of JavaScript, 896 LOC of Python = 1369 LOC