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). 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/: Get a specific SWeeT by its id. - [GET] /api/sweets/q?who=&what=&where= : 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 > `` $ 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 /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 ------------------ * 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](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.