1 |
swtstore (Sweet Store) |
2 |
====================== |
3 |
|
4 |
---- |
5 |
|
6 |
|
7 |
Introduction |
8 |
------------ |
9 |
|
10 |
This is the sweet store application. |
11 |
The store for the decentralized, semantic, social web tweets a.k.a SWeeTs! |
12 |
|
13 |
This README is about installing, configuring and running/deploying this |
14 |
application. If you want to know more about SWeeTs, please go to |
15 |
[wiki.janastu.org/Sweet_Web](http://janastu.org/technoscience/index.php/Sweet_Web) and |
16 |
[trac.pantoto.org/sweet-web](http://trac.pantoto.org/sweet-web). |
17 |
|
18 |
This application acts as the repository store for all the SWeeTs that are |
19 |
generated from the clients registered with the sweet store. It provides |
20 |
query APIs to query the SWeeTs. |
21 |
|
22 |
It also provides user management to manage the users of the swtstore. |
23 |
|
24 |
All the APIs of the swtstore are accessed by using an access token which is |
25 |
generated by the swtstore when an user authorizes a third-party application |
26 |
through OAuth. |
27 |
|
28 |
Sweet store provides the following APIs: |
29 |
|
30 |
- [GET] /api/sweets/<id>: Get a specific SWeeT by its id. |
31 |
|
32 |
- [GET] /api/sweets/q?who=<username>&what=<contextname>&where=<URL> : |
33 |
This API is for querying sweet based on the who, what and where |
34 |
parameters. |
35 |
This API does not support querying based on parameters mentioned in how, |
36 |
but will be supported in future. Right now, the client can get sweets |
37 |
based on the above mentioned three parameters, and as the 'how' part is |
38 |
a JSON, it is trivial to do further filtering based on parameters of |
39 |
'how' by the client. |
40 |
|
41 |
- [POST] /api/sweets : Post a SWeeT to this swtstore with the data in the |
42 |
body of the request. The data or payload is a list of sweets. Even if you |
43 |
are sending one sweet, make sure that the sweet is in a list. |
44 |
|
45 |
- [GET] /api/users/me : Get a JSON details of the current user logged in. |
46 |
|
47 |
|
48 |
Any third-party client side application can communicate with the swtstore |
49 |
using these APIs, provided they have a valid access token. |
50 |
|
51 |
|
52 |
Pre-requisites |
53 |
-------------- |
54 |
|
55 |
The swtstore application is written in Python and uses a relational database. |
56 |
|
57 |
Hence, the dependencies of this application are Python and any relational database |
58 |
supported by SQLAlchemy. |
59 |
|
60 |
Most common RDBMS supported by SQLAlchemy are MySQL, Postgresql. |
61 |
|
62 |
For more information on supported databases see |
63 |
[here](http://docs.sqlalchemy.org/en/rel_0_9/dialects/index.html). |
64 |
|
65 |
Also, make sure you have [pip](https://pip.pypa.io/en/latest/) installed, as |
66 |
swtstore depends of few external python packages. |
67 |
|
68 |
**NOTE: Make sure you have the pre-requisites installed before following the |
69 |
installation steps.** |
70 |
|
71 |
|
72 |
Installing |
73 |
---------- |
74 |
|
75 |
* Clone the repository from [https://git.pantoto.org/sweet-web/sweet-web-engine](https://git.pantoto.org/sweet-web/sweet-web-engine) |
76 |
|
77 |
> $ git clone --recursive https://git.pantoto.org/sweet-web/sweet-web-engine.git |
78 |
|
79 |
If you have already cloned the repo, and then reading this README, you have |
80 |
to get the submodules. Run this from the top-level of this repo: |
81 |
|
82 |
> $ git submodule init |
83 |
> $ git submodule update |
84 |
|
85 |
|
86 |
* It is recommended to do the installation inside a python virtual |
87 |
environment. |
88 |
For deploying on a server, it depends on how you have setup your server |
89 |
environment. |
90 |
If you think, you know what you are doing and don't need the virtual |
91 |
environment, you can skip to the next step. |
92 |
|
93 |
Initialize a python virtual environment using `virtualenv` in the same directory |
94 |
where you cloned the repository in the above step. Now, activate the |
95 |
environment |
96 |
|
97 |
> ``$ source <path/to/your/current-virtual-env>/bin/activate `` |
98 |
|
99 |
See [http://www.virtualenv.org/en/latest/virtualenv.html](http://www.virtualenv.org/en/latest/virtualenv.html) for more details about `virtualenv`. |
100 |
|
101 |
* Run the setup.py script to install `` python setup.py install `` |
102 |
|
103 |
|
104 |
You're done with the installation step. |
105 |
|
106 |
Now you need to configure swtstore to run it correctly. |
107 |
|
108 |
|
109 |
Configure swtstore |
110 |
------------------ |
111 |
|
112 |
* Make sure you have configured the user management module with correct values. |
113 |
|
114 |
* Copy the contents of ``sample_config.py`` inside the ``swtstore`` directory |
115 |
into ``config.py`` inside ``swtstore`` directory itself. |
116 |
|
117 |
Assuming you are using a \*-nix based system, and you are in the root directory |
118 |
of the codebase, |
119 |
|
120 |
`` $ cp swtstore/sample_config.py swtstore/config.py`` |
121 |
|
122 |
* Edit the config.py file, and change the values accordingly. |
123 |
|
124 |
* Now, you have to setup the database for the swtstore application. But |
125 |
fortunately, the creation of database and tables have also been scripted, so |
126 |
all you need to do is run the ``dbsetup.py`` script. |
127 |
`` $ python dbsetup.py `` |
128 |
|
129 |
**NOTE:** Please remember that all these configuration step is necessary and is |
130 |
required whether you are running the application locally or deploying it on a |
131 |
server. |
132 |
|
133 |
|
134 |
|
135 |
Running the server locally |
136 |
-------------------------- |
137 |
|
138 |
Run the runserver.py script to run the server locally, |
139 |
|
140 |
> `` $ python runserver.py `` |
141 |
|
142 |
This runs the application locally, on port 5001. So you can direct your browser |
143 |
to http://localhost:5001 |
144 |
|
145 |
|
146 |
|
147 |
Deploying the application |
148 |
------------------------- |
149 |
|
150 |
SwtStore is deployed as a WSGI application server. |
151 |
|
152 |
The wsgi script to deploy the application is provided (its called |
153 |
`swtstore.wsgi`). |
154 |
Point your webserver like Apache, or Nginx to point to the `swtstore.wsgi` |
155 |
script. |
156 |
|
157 |
See Apache WSGI configuration here: |
158 |
[http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIScriptAlias.html](http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIScriptAlias.html) |
159 |
|
160 |
See Nginx WSGI configuration here: |
161 |
[http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html](http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html) |
162 |
|
163 |
|
164 |
Help / Feedback |
165 |
--------------- |
166 |
|
167 |
If you need any help, or have any questions, comments or feedback, you can contact at |
168 |
rayanon or arvind or bhanu at servelots.com |
169 |
|
170 |
You can also join channel #servelots on freenode network, using your favourite |
171 |
IRC client. We usually hang out at #servelots. |
172 |
|
173 |
|
174 |
License |
175 |
------- |
176 |
|
177 |
BSD Licensed. |
178 |
|
179 |
See LICENSE for more details. |
180 |
|
181 |
|
182 |
Known Issues |
183 |
------------ |
184 |
|
185 |
* Infinite loop in Persona sign-in flow. When the backend API /users/login fail |
186 |
to connect to the Mozilla Persona APIs (connection timed out etc.) - the |
187 |
/users/login returns a 500, and then the Persona Javascript SDK calls the |
188 |
logout API /users/logout and then it calls the login API again; as a result |
189 |
the entire sign-in flow falls in a infinite loop. |
190 |
|
191 |
* Automatic log out from Persona. Persona forces a user to login, again, when he |
192 |
opens SWeeT store while being logged into Persona, through a different |
193 |
site. Persona requires the user, every time, to explicilty say that he is |
194 |
agreeing to share the email adress with a site that is using Persona API. |