onurgu/swtstore

The server-side store and query interface for decentralized, semantic, social web tweets aka SWeeTs!

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.

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 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.

  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 installed, as swtstore depends of few external python packages. See here 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 https://git.pantoto.org/sweet-web/sweet-web-engine.git

• 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 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

• Create a directory named logs. This directory will contain the log file of sweet store.

• 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 psycopg2 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

See Nginx WSGI configuration here: 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.