Flask rewrite
[pleaseshare.git] / README.rst
1 PleaseShare
2 ===========
3
4 PleaseShare is a file-sharing website that aims to decentralize
5 file-sharing through the use of bittorrent, DHT, and webseeds.
6
7
8 Get started
9 -----------
10
11 Retrieve the project from gitorious_ or github_:
12
13 .. _gitorious: https://git.gitorious.org/pleaseshare/pleaseshare.git
14 .. _github: https://github.com/mathieui/pleaseshare.git
15
16 ::
17
18     $ git clone git://gitorious.org/pleaseshare/pleaseshare.git
19
20 Then install the dependencies (assuming you are using a virtualenv):
21
22 ::
23
24     $ cd pleaseshare
25     $ pip install -r requirements.txt
26     $ mkdir -p pleaseshare/uploads
27
28 Now you can start coding, testing, etc.
29
30 Install
31 -------
32
33 (do the Get started thing before that)
34
35 First, edit the variables in pleaseshare/settings.cfg to fit your needs,
36 everything is properly documented inside the file, but you MUST consider
37 changing the following:
38
39 - ``SECRET_KEY`` and ``WTF_CSRF_SECRET_KEY``, both set to the value of a local ``key`` variable
40 - ``SQLALCHEMY_DATABASE_URI`` for database connection settings
41 - ``MAX_CONTENT_LENGTH`` for the maximal upload file size
42
43 Once everything is set, you only have to create the database:
44
45 ::
46
47     $ ./make_db.py
48
49
50 In order to deploy PleaseShare, you can follow the flask `deployment guide`_.
51
52 .. _deployment guide: http://flask.pocoo.org/docs/deploying/
53
54 My favourite deployment option is uwsgi + nginx/lighttpd
55
56 Example uwsgi+nginx deployment
57 ------------------------------
58
59 ``uwsgi.ini`` file:
60
61 ::
62
63     [uwsgi]
64     socket = 127.0.0.1:4444
65     master = true
66     plugin = python3
67     chdir = /home/flask/pleaseshare/
68     module = pleaseshare:app
69     processes = 4
70
71
72
73 Nginx configuration section:
74
75 :: 
76
77     server {
78         listen                  80;
79         server_name             share.example.com;
80         client_max_body_size    50m;
81
82         location / {
83             include             uwsgi_params;
84             uwsgi_pass          127.0.0.1:4444;
85         }
86     }
87
88     server {
89         listen                  80;
90         server_name             files.example.com;
91         client_max_body_size    200k;
92
93         location / {
94             root                /home/flask/pleaseshare/uploads/;
95             autoindex           off;
96         }
97     }
98
99 (assuming ``UPLOAD_FOLDER`` is set to ``"uploads"``, and ``UPLOADED_FILES_URL``
100 to ``"http://files.example.com/"``)
101
102
103 I also usually use supervisord_ to manage my python web applications:
104
105 ::
106
107     [program:share]
108     command=uwsgi uwsgi.ini
109     directory=/home/flask/pleaseshare/
110     user=flask
111     redirect_stderr=true
112     autostart=true
113     autorestart=true
114
115
116 .. _supervisord: http://supervisord.org/
117
118 But manually running ``uwsgi uwsgi.ini`` works too.
119
120
121 Misc
122 ----
123
124 Some indications about how webseeds work might be in order.
125
126 - When the torrent has a single file, then it’s easy: the webseed is the complete url of the file.
127 - When the torrent is multifile, then the webseed url is the url of the parent directory (I’m talking about the torrents in PleaseShare, which are always contained in a parent directory named after the archive name).
128
129 For example, you upload a toto.tar.gz archive, you will have a url like /view/48a3-[…]/,
130 containing a 'toto' directory, which will contain the files inside the archive.
131
132 The webseed url should **not** contain the 'toto' directory, but the parent
133 level; and, of course, file indexing should be disabled, or the file generated
134 by the webserver might cause problems to some torrent clients.
135
136 So let’s say you want to add a source to the torrent using your personal
137 webserver (again for the toto.tar.gz torrent), you will have to put something
138 like that as a webseed: http://my.example.com/uploads/ which will contain a ``toto``
139 directory.
140
141 License
142 -------
143
144 PleaseShare is released under the terms of the `GNU Affero General
145 Public License v3`_.
146
147 PleaseShare also contains some files from the `Deluge torrent client`_,
148 which is licenced under the `GNU General Public Licence v3`_.
149
150 .. _GNU Affero General Public License v3 : http://www.gnu.org/licenses/agpl-3.0.html
151 .. _Deluge torrent client : http://deluge-torrent.org/
152 .. _GNU General Public Licence v3 : https://www.gnu.org/licenses/gpl-3.0.html
153
154