Tahrir
======

Tahrir is `Arabic for Liberation
<http://en.wikipedia.org/wiki/Tahrir_Square>`_.

Tahrir is also a `Pyramid <http://www.pylonsproject.org/>`_ app for issuing
your own `Open Badges <https://wiki.mozilla.org/Badges>`_.

The name is total overkill.

You can see Tahrir deployed in production `here
<https://badges.fedoraproject.org/>`_. The staging instance lives `here
<https://badges.stg.fedoraproject.org/>`_.

(On the side, if you have ideas for new *Fedora* badges, you can file them on
`this trac instance <https://fedorahosted.org/fedora-badges/>`_.)


Installing... just to try it out
--------------------------------

You can always::

    $ pip install tahrir

Deploying for reals
-------------------

It's `packaged for Fedora and epel6
<https://apps.fedoraproject.org/packages/python-tahrir>`_.  The authors use an
`Ansible <http://ansibleworks.com>`_ playbook to deploy Tahrir in production.

You can find our repo `here
<http://infrastructure.fedoraproject.org/infra/ansible/>`_, our playbook `here
<http://infrastructure.fedoraproject.org/infra/ansible/playbooks/groups/badges-web.yml>`_,
and our tahrir role `here
<http://infrastructure.fedoraproject.org/infra/ansible/roles/badges-frontend/>`_.

Building a configuration file
-----------------------------

Get a sample configuration file::

    $ wget https://raw.github.com/fedora-infra/tahrir/master/production.ini -O
    tahrir.ini

Edit it to your liking.  In particular you will need to change the
following values under the ``[server:main]`` section:

 - ``host`` = yoursite.com
 - ``port`` = 80

And the following values under the ``[app:pyramid]`` section:

  - ``tahrir.admin`` = "comma-delimited list of admin email addresses"
  - ``tahrir.title`` = "just badgin' around"
  - ``tahrir.pngs.uri`` = /home/user/badges/pngs
  - ``tahrir.base_url`` = "yoursite.com"

Setting up the DB
-----------------

Run the following command before starting the server::

    $ initialize_tahrir_db tahrir.ini

Running
-------

Start the server like so (subsitute ``tahrir.ini`` with the ``.ini`` file
you want to use::

    $ pserve tahrir.ini

You can pass the ``--reload`` flag to this command to automatically restart
the server in the event that the code is altered.

Reporting Bugs
--------------

If you find bugs in Tahrir or have ideas for enhancements, please report them
at https://github.com/fedora-infra/tahrir/issues.

Hacking
-------

If you'd like to contribute to Tahrir or just poke at the code, you can use the
following instructions to set up a development environment.

Create an account on Fedora Account Systems (FAS) at
https://admin.fedoraproject.org/accounts. Make sure you have Python 2.7 or
above installed on your system. Then, install the Python version of
virtualenvwrapper (in Fedora)::

	$ sudo yum -y install python-virtualenvwrapper

In Ubuntu, you can do the same with::

	$ sudo apt-get install python-setuptools
	$ sudo apt-get install python-virtualenv
	$ sudo easy-install pip
	$ sudo pip install python-virtualenvwrapper

After installing virtualenvwrapper, you'll need to set it up for the
first time::

    $ export WORKON_HOME=~/.virtualenvs/
    $ mkdir -p $WORKON_HOME
    $ source /usr/local/bin/virtualenvwrapper.sh

You'll want to add ``source /usr/local/bin/virtualenvwrapper.sh`` to
your ``.bashrc``.

Then, to set up Tahrir, follow these steps::

	$ git clone git://github.com/fedora-infra/tahrir.git
	$ cd tahrir
	$ mkvirtualenv tahrir
	(tahrir)$ python setup.py develop
	(tahrir)$ cp development.ini.sample development.ini
	(tahrir)$ cp secret.ini.sample secret.ini
	(tahrir)$ initialize_tahrir_db development.ini
	(tahrir)$ pserve --reload development.ini

The pserve command should output "starting HTTP server on
https://localhost:8000". Login to https://localhost:8000 in your web browser
using your FAS account username and password.  In order to make
yourself an admin of the local copy of tahrir, edit the ``development.ini`` file
and append ``YOUR_FAS_USERNAME@fedoraproject.org`` to the ``tahrir.admin`` option.
When you login, you should now be able to see the admin view of tahrir in your
local copy at http://localhost:8000/admin.

Windows (32 and 64 bit versions):
---------------------------------

For problems like::

    c:\env\tahrir>c:\env\Scripts\initialize_tahrir_db development.ini
    Error: pkg_resources.DistributionNotFound: simplejson

and::

    c:\env\tahrir>c:\env\Scripts\easy_install simplejson
    Error: raise ValueError(str(list(result.keys())))
    ValueError: [u'path']

Follow these instructions:

1.  Download and install mingw from
    http://code.google.com/p/mingw-builds/downloads/detail?name=i686-mingw32-gcc-4.7.0-release-c,c%2b%2b,fortran-sjlj.zip&can=2&q=
    Extract the contents of this folder to ``c:\mingw``.

2.  Download and install setuptools if not already present. This can be done by
    running ez_setup.py from c:\Python2x.

3.  Create a configuration file for distutils i.e. create a file distutils.cfg
    at the following location::

        C:\Python2x\Lib\distutils\distutils.cfg

    Add the following line to it::

        [build] compiler=mingw32

4.  Now open command prompt and use easy_install to install simplejson::

        C:\env\tahrir>c:\env\Scripts\easy_install simplejson

This will install simplejson in Python2x\Lib\site-packages\. A few other
packages -- namely httplib2 -- may have to be installed the same way before the
``initialize_tahrir_db`` command can be executed.
