swtstore (Sweet Store)

======================

----

Introduction

------------

This is the sweet store application.

The store for the decentralized, semantic, social web tweets a.k.a SWeeTs!

This README is about installing, configuring and running/deploying this

application. If you want to know more about SWeeTs, please go to

[wiki.janastu.org/Sweet_Web](http://janastu.org/technoscience/index.php/Sweet_Web) and

[trac.pantoto.org/sweet-web](http://trac.pantoto.org/sweet-web).

This application acts as the repository store for all the SWeeTs that are

generated from the clients registered with the sweet store. It provides

query APIs to query the SWeeTs.

It also provides user management to manage the users of the swtstore.

All the APIs of the swtstore are accessed by using an access token which is

generated by the swtstore when an user authorizes a third-party application

through OAuth.

Sweet store provides the following APIs:

    - [GET] /api/sweets/<id>: Get a specific SWeeT by its id.

    - [GET] /api/sweets/q?who=<username>&what=<contextname>&where=<URL> :

      This API is for querying sweet based on the who, what and where

      parameters.

      This API does not support querying based on parameters mentioned in how,

      but will be supported in future. Right now, the client can get sweets

      based on the above mentioned three parameters, and as the 'how' part is

      a JSON, it is trivial to do further filtering based on parameters of

      'how' by the client.

    - [POST] /api/sweets : Post a SWeeT to this swtstore with the data in the

    body of the request. The data or payload is a list of sweets. Even if you

    are sending one sweet, make sure that the sweet is in a list.

    - [GET] /api/users/me : Get a JSON details of the current user logged in.

Any third-party client side application can communicate with the swtstore

using these APIs, provided they have a valid access token.

Pre-requisites

--------------

The swtstore application is written in Python and uses a relational database.

Hence, the dependencies of this application are:

  * Python 2.7. See [here](https://www.python.org/about/gettingstarted/)

    for more details on installing Python.

  * any relational database supported by SQLAlchemy. Most common RDBMS

    supported by SQLAlchemy are MySQL, Postgresql.

    For more information on supported databases see

    [here](http://docs.sqlalchemy.org/en/rel_0_9/dialects/index.html).

    _Installing and setting up a database like MySQL or Postgresql is out of scope

    of this document. Please search the Internet to get help about installing and

    setting up a RDBMS._

  * Also, make sure you have [pip](https://pip.pypa.io/en/latest/) installed, as

    swtstore depends of few external python packages.

    See [here](https://pip.pypa.io/en/latest/) to get more details.

**NOTE: Make sure you have the pre-requisites installed before following the

installation steps.**

Installing

----------

* Clone the repository from <https://git.pantoto.org/sweet-web/sweet-web-engine>

  > `` $ git clone --recursive https://git.pantoto.org/sweet-web/sweet-web-engine.git ``

  If you have already cloned the repo, and then reading this README, you have

  to get the submodules. Run this from the top-level of this repo:

  > `` $ git submodule init ``

  > `` $ git submodule update ``

* It is recommended to do the installation inside a python virtual

  environment.

  For deploying on a server, it depends on how you have setup your server

  environment.

  If you think, you know what you are doing and don't need the virtual

  environment, you can skip to the next step.

  Initialize a python virtual environment using `virtualenv` in the same directory

  where you cloned the repository in the above step. Now, activate the

  environment

  > ``$ source <path/to/your/current-virtual-env>/bin/activate ``

  See [http://www.virtualenv.org/en/latest/virtualenv.html](http://www.virtualenv.org/en/latest/virtualenv.html) for more details about `virtualenv`.

* Run the setup.py script to install  `` python setup.py install ``

You're done with the installation step.

Now you need to configure swtstore to run it correctly.

Configure swtstore

------------------

* Make sure you have configured the user management module with correct values.

* Copy the contents of ``sample_config.py`` inside the ``swtstore`` directory

  into ``config.py`` inside ``swtstore`` directory itself.

  Assuming you are using a \*-nix based system, and you are in the root directory

  of the codebase,

  > `` $ cp swtstore/sample_config.py swtstore/config.py``

* Install the required driver for using database mentioned in the

  SQLALCHEMY_DATABASE_URI. Install pyscopg2 if you have chosen postgresql as

  the database to use.

  > `` $ pip install psycopg2 ``

  Install oursql if you have chosen mysql as the database to use.

  > `` $ pip install oursql``

  You would also have to install dependecies, for using mysql:

  - python-dev

  - libmysqlclient-dev

  Install these dependencies from the package manager of your distribution.

* Edit the config.py file, and change the values accordingly.

* Now, you have to setup the database for the swtstore application. But

  fortunately, the creation of database and tables have also been scripted, so

  all you need to do is run the ``dbsetup.py`` script.

  > `` $ python dbsetup.py ``

**NOTE:** Please remember that all these configuration step is necessary and is

required whether you are running the application locally or deploying it on a

server.

Running the server locally

--------------------------

Run the runserver.py script to run the server locally,

> `` $ python runserver.py ``

This runs the application locally, on port 5001. So you can direct your browser

to http://localhost:5001

Deploying the application

-------------------------

SwtStore is deployed as a WSGI application server.

The wsgi script to deploy the application is provided (its called

`swtstore.wsgi`).

Point your webserver like Apache, or Nginx to point to the `swtstore.wsgi`

script.

See Apache WSGI configuration here:

[http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIScriptAlias.html](http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIScriptAlias.html)

See Nginx WSGI configuration here:

[http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html](http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html)

Help / Feedback

---------------

If you need any help, or have any questions, comments or feedback, you can contact at

rayanon or arvind or bhanu at servelots.com

You can also join channel #servelots on freenode network, using your favourite

IRC client. We usually hang out at #servelots.

License

-------

BSD Licensed.

See LICENSE for more details.

Known Issues

------------

* Infinite loop in Persona sign-in flow. When the backend API /users/login fail

  to connect to the Mozilla Persona APIs (connection timed out etc.) - the

  /users/login returns a 500, and then the Persona Javascript SDK calls the

  logout API /users/logout and then it calls the login API again; as a result

  the entire sign-in flow falls in a infinite loop.

* Automatic log out from Persona. Persona forces a user to login, again, when he

  opens SWeeT store while being logged into Persona, through a different

  site. Persona requires the user, every time, to explicilty say that he is

  agreeing to share the email adress with a site that is using Persona API.