aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--.github/CONTRIBUTING.md74
-rw-r--r--ARCHITECTURE.md46
-rw-r--r--FAQ.md23
-rw-r--r--README.md141
4 files changed, 196 insertions, 88 deletions
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 3764eb7c4..989087728 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -7,30 +7,90 @@ Interesting in contributing? Awesome :)
7 * [Give your feedback](#give-your-feedback) 7 * [Give your feedback](#give-your-feedback)
8 * [Develop on the Server side](#develop-on-the-server-side) 8 * [Develop on the Server side](#develop-on-the-server-side)
9 * [Develop on the Client side](#develop-on-the-client-side) 9 * [Develop on the Client side](#develop-on-the-client-side)
10 * [Get started with development](#get-started-with-development)
10 * [Write documentation](#write-documentation) 11 * [Write documentation](#write-documentation)
11 12
12 13
13## Give your feedback 14## Give your feedback
14 15
15Even if you are not a developer, or you do not want to develop on PeerTube you can give a feedback on potential bugs, features that you are interested in, user interace, design, decentralized architecture... 16You don't need to know how to code to start contributing to PeerTube! Other
17contributions are very valuable too, among which: you can test the software and
18report bugs, you can give feedback on potential bugs, features that you are
19interested in, user interace, design, decentralized architecture...
16 20
17 21
22## Development
23
18## Develop on the Server side 24## Develop on the Server side
19 25
20The server is a web server developed with [NodeJS](https://nodejs.org)/[Express](http://expressjs.com). 26The server is a web server developed with
27[NodeJS](https://nodejs.org)/[Express](http://expressjs.com).
21 28
22Newcommer? You can find a documentation of the server code/architecture [here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/server/code.md). 29Newcomer? You can find a documentation of the server code/architecture
30[here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/server/code.md).
23 31
24Do not hesitate to talk about the functionnality you want to develop by creating an issue :) 32Don't hesitate to talk about features you want to develop by creating an issue
33before you start working on them :).
25 34
26 35
27## Develop on the Client side 36## Develop on the Client side
28 37
29The client is a web application developed with [TypeScript](https://www.typescriptlang.org/)/[Angular2](https://angular.io/) 38The client is a web application developed with
39[TypeScript](https://www.typescriptlang.org/)/[Angular2](https://angular.io/).
40
41Newcomer? You can find a documentation of the server code/architecture
42[here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/client/code.md).
43
44
45## Get started with development
46
47In this mode, the server will run requests between instances more quickly, the
48video durations are limited to a few seconds.
49
50### Prerequisites
51
52First, make sure that you have followed the steps to install the dependencies.
53
54Then, create a postgres database and user with the values set in the
55`config/default.yaml` file. For instance, if you do not change the values
56there, the following commands would create a new database called `peertube_dev`
57and a postgres user called `peertube` with password `peertube`:
58
59```bash
60 # sudo -u postgres createuser -P peertube
61 Enter password for new role: peertube
62 # sudo -u postgres createdb -O peertube peertube_dev
63```
64
65### Server side
66
67To develop on the server-side:
68
69```bash
70 $ npm run dev:server
71```
72
73Then, the server will listen on `localhost:9000`. When server source files
74change, these are automatically recompiled and the server will automatically
75restart.
76
77### Client side
78
79To develop on the client side:
80
81```bash
82 $ npm run dev:client
83```
84
85The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
86Client files are automatically compiled on change, and the web browser will
87reload them automatically thanks to hot module replacement.
30 88
31Newcommer? You can find a documentation of the server code/architecture [here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/client/code.md). 89**Username**: *root* <br/>
90**Password**: *test*
32 91
33 92
34## Write documentation 93## Write documentation
35 94
36You can help to write the documentation of the REST API, code, architecture, demonstrations... 95You can help to write the documentation of the REST API, code, architecture,
96demonstrations...
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ac62fa4b7..ecc4d2d40 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -2,25 +2,39 @@
2 2
3## Vocabulary 3## Vocabulary
4 4
5 - **Fediverse:** several servers following each others 5 - **Fediverse:** several servers following each others.
6 - **Instance:** a server which runs PeerTube in the fediverse 6 - **Instance:** a server which runs PeerTube in the fediverse.
7 - **Origin instance:** the instance on which the video was uploaded and which is seeding (WebSeed protocol) the video 7 - **Origin instance:** the instance on which the video was uploaded and which
8 - **Following:** the action of a PeerTube instance which will follow another instance (subscribe to its videos) 8 is seeding (through the WebSeed protocol) the video.
9 - **Following:** the action of a PeerTube instance which will follow another
10 instance (subscribe to its videos).
9 11
10## Base 12## Base
11 13
12### Communications 14### Communications
13 * All the communications between the instances are signed with [Linked Data Signatures](https://w3c-dvcg.github.io/ld-signatures/) with the private key of the account that made the action 15 * All the communication between the instances are signed with [Linked Data
14 * We use the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol (only server-server for now). Object models could be found in [shared/models/activitypub directory](https://github.com/Chocobozzz/PeerTube/tree/develop/shared/models/activitypub). 16 Signatures](https://w3c-dvcg.github.io/ld-signatures/) with the private key
15 * All the requests are retried several times if they fail 17 of the account that authored the action.
16 * The maximum of points would be defined 18 * We use the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol (only
19 server-server for now). Object models could be found in
20 [shared/models/activitypub
21 directory](https://github.com/Chocobozzz/PeerTube/tree/develop/shared/models/activitypub).
22 * All the requests are retried several times if they fail.
23 * The maximum of points would be defined.
17 24
18### Instance 25### Instance
19 * An instance has a websocket tracker which is responsible for all the video uploaded in it 26 * An instance has a websocket tracker which is responsible for all the video
20 * An instance has an administrator that can follow other instances 27 uploaded in it.
21 * An instance can be configured to follow back automatically 28 * An instance has an administrator that can follow other instances.
22 * An instance can blacklist other instances (only used in "follow back" mode) 29 * An instance can be configured to follow back automatically.
23 * An instance cannot choose which other instance follow it, but it can decide to **reject all** followers 30 * An instance can blacklist other instances (only used in "follow back"
24 * After having uploaded a video, the instance seeds it (WebSeed protocol) 31 mode).
25 * If a user wants to watch a video, he asks its instance the magnet URI and the frontend adds the torrent (with WebTorrent), creates the HTML5 video player and streams the file into it 32 * An instance cannot choose which other instances follow it, but it can
26 * A user watching a video seeds it too (BitTorrent) so another user who is watching the same video can get the data from the origin server and the user 1 (etc) 33 decide to **reject all** followers.
34 * After having uploaded a video, the instance seeds it (WebSeed protocol).
35 * If a user wants to watch a video, they ask its instance the magnet URI and
36 the frontend adds the torrent (with WebTorrent), creates the HTML5 video
37 player and streams the file into it.
38 * A user watching a video seeds it too (BitTorrent). Thus another user who is
39 watching the same video can get the data from the origin server and other
40 users watching it.
diff --git a/FAQ.md b/FAQ.md
index 7e2b3339c..06c86ce10 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -2,25 +2,31 @@
2 2
3## If nobody watches a video, is it seeded? 3## If nobody watches a video, is it seeded?
4 4
5Yes, the origin server always seeds videos uploaded on it through [Webseed](http://www.bittorrent.org/beps/bep_0019.html). 5Yes, the origin server always seeds videos uploaded on it thanks to
6[Webseed](http://www.bittorrent.org/beps/bep_0019.html).
6 7
7 8
8## What is WebSeed? 9## What is WebSeed?
9 10
10It is a BitTorrent extension that allow a server to seed a file through HTTP. It just need to serve statically a file, and then the clients will request chunks with a Content-Range HTTP header. 11It is a BitTorrent extension that allows a server to seed a file through HTTP.
12It just needs to statically serve a file, then the clients will request chunks
13with a `Content-Range` HTTP header.
11 14
12 15
13## If a client requests each chunk of a video through HTTP, the server be overloaded! 16## If a client requests each chunk of a video through HTTP, will the server be overloaded?
14 17
15Not really. Reverse proxies like Nginx handle very well requests of static files. In my tests it can send chunks at 10MB/s without consuming more than 5% of CPU on a very small VPS. 18Not really. Reverse proxies like Nginx handle very well requests of static
19files. In my tests, it can send chunks at 10MB/s without consuming more than 5%
20of CPU on a very small VPS.
16 21
17 22
18## An index of all videos of servers you follow won't be too large for small servers? 23## Will an index of all the videos of servers you follow be too large for small servers?
19 24
20No, 1000000 videos will represent around 2GB on PostgreSQL. It is acceptable for a video platform. 25In our benchmarks, 1,000,000 videos takes around 2GB of storage on PostgreSQL.
26We think it is acceptable for a video platform.
21 27
22 28
23## What kind of videos can I upload? 29## What codecs can I use for the videos I want to upload?
24 30
25WEBM, MP4 or OGV videos. 31WEBM, MP4 or OGV videos.
26 32
@@ -29,4 +35,5 @@ WEBM, MP4 or OGV videos.
29 35
30If you already have followers, you can't. 36If you already have followers, you can't.
31 37
32If you don't: update your configuration and run `NODE_ENV=production npm run update-host` to update the torrent files. 38If you don't have any followers, update your configuration and run
39`NODE_ENV=production npm run update-host` to update the torrent files.
diff --git a/README.md b/README.md
index 077d6b8f0..094d81c4a 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,14 @@
3</h1> 3</h1>
4 4
5<h4 align="center"> 5<h4 align="center">
6Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with <a href="https://github.com/feross/webtorrent">WebTorrent</a>. 6Federated (ActivityPub) video streaming platform using P2P (BitTorrent)
7directly in the web browser with <a href="https://github.com/feross/webtorrent">WebTorrent</a>.
7</h4> 8</h4>
8 9
9**PeerTube is sponsored by [Framasoft](https://framatube.org/#en), a non-profit that promotes, spreads and develops free-libre software. If you want to support this project, please [consider donating them](https://soutenir.framasoft.org/en/).** 10**PeerTube is sponsored by [Framasoft](https://framatube.org/#en), a non-profit
11that promotes, spreads and develops free culture in general, and free-libre
12software in particular. If you want to support this project, please [consider
13donating them](https://soutenir.framasoft.org/en/).**
10 14
11<p align="center"> 15<p align="center">
12 <strong>Client</strong> 16 <strong>Client</strong>
@@ -58,20 +62,28 @@ Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly
58 62
59## Demonstration 63## Demonstration
60 64
61Want to see in action? 65Want to see it in action?
62 66
63 * [Demo server](http://peertube.cpy.re) 67 * [Demo server](http://peertube.cpy.re)
64 * [Video](https://peertube.cpy.re/videos/watch/f78a97f8-a142-4ce1-a5bd-154bf9386504) to see how the "decentralization feature" looks like 68 * [Video](https://peertube.cpy.re/videos/watch/f78a97f8-a142-4ce1-a5bd-154bf9386504)
65 * Experimental demo servers that share videos (they are in the same network): [peertube2](http://peertube2.cpy.re), [peertube3](http://peertube3.cpy.re). Since I do experiments with them, sometimes they might not work correctly. 69 to see how the "decentralization feature" looks like
70 * Experimental demo servers that share videos (they are in the same
71 network): [peertube2](http://peertube2.cpy.re),
72 [peertube3](http://peertube3.cpy.re). Since I do experiments with them,
73 sometimes they might not work correctly.
66 74
67## Why 75## Why
68 76
69We can't build a FOSS video streaming alternatives to YouTube, Dailymotion, Vimeo... with a centralized software. One organization alone cannot have enough money to pay bandwidth and video storage of its server. 77We can't build a FOSS video streaming alternatives to YouTube, Dailymotion,
78Vimeo... with a centralized software. One organization alone may not have
79enough money to pay for bandwidth and video storage of its servers.
70 80
71So we need to have a decentralized network (as [Diaspora](https://github.com/diaspora/diaspora) for example). 81So we need to have a decentralized network of servers seeding videos (as
72But it's not enough because one video could become famous and overload the server. 82[Diaspora](https://github.com/diaspora/diaspora) for example). But it's not
73It's the reason why we need to use a P2P protocol to limit the server load. 83enough because one video could become famous and overload the server. It's the
74Thanks to [WebTorrent](https://github.com/feross/webtorrent), we can make P2P (thus bittorrent) inside the web browser right now. 84reason why we need to use a P2P protocol to limit the server load. Thanks to
85[WebTorrent](https://github.com/feross/webtorrent), we can make P2P (thus
86bittorrent) inside the web browser, as of today.
75 87
76## Features 88## Features
77 89
@@ -111,7 +123,8 @@ Thanks to [WebTorrent](https://github.com/feross/webtorrent), we can make P2P (t
111 123
112## Installation 124## Installation
113 125
114See [wiki](https://github.com/Chocobozzz/PeerTube/wiki) for complete installation commands. 126See [wiki](https://github.com/Chocobozzz/PeerTube/wiki) for complete
127installation commands.
115 128
116### Front compatibility 129### Front compatibility
117 130
@@ -128,12 +141,16 @@ See [wiki](https://github.com/Chocobozzz/PeerTube/wiki) for complete installatio
128 141
129#### Debian 142#### Debian
130 143
131 1. Install NodeJS 8.x (current LTS): [https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions) 144 1. Install NodeJS 8.x (current LTS):
132 2. Install yarn: [https://yarnpkg.com/en/docs/install](https://yarnpkg.com/en/docs/install) 145 [https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)
146 2. Install yarn:
147 [https://yarnpkg.com/en/docs/install](https://yarnpkg.com/en/docs/install)
133 4. Run: 148 4. Run:
134 149
150```bash
135 $ apt-get update 151 $ apt-get update
136 $ apt-get install ffmpeg postgresql openssl 152 $ apt-get install ffmpeg postgresql openssl
153```
137 154
138#### Ubuntu 16.04 155#### Ubuntu 16.04
139 156
@@ -141,112 +158,122 @@ See [wiki](https://github.com/Chocobozzz/PeerTube/wiki) for complete installatio
141 2. Install yarn: (same as Debian) 158 2. Install yarn: (same as Debian)
142 3. Run: 159 3. Run:
143 160
161```bash
144 $ apt-get update 162 $ apt-get update
145 $ apt-get install ffmpeg postgresql openssl 163 $ apt-get install ffmpeg postgresql openssl
164```
146 165
147#### Arch Linux 166#### Arch Linux
148 167
149 1. Run: 168 1. Run:
150 169
170```bash
151 $ pacman -S nodejs yarn ffmpeg postgresql openssl 171 $ pacman -S nodejs yarn ffmpeg postgresql openssl
172```
152 173
153#### Other distribution... (PR welcome) 174#### Other distributions
154 175
176Feel free to update this README file in a pull request!
155 177
156### Sources 178### Build from the sources
157 179
180```bash
158 $ git clone -b master https://github.com/Chocobozzz/PeerTube 181 $ git clone -b master https://github.com/Chocobozzz/PeerTube
159 $ cd PeerTube 182 $ cd PeerTube
160 $ yarn install 183 $ yarn install
161 $ npm run build 184 $ npm run build
185```
162 186
163## Usage 187## Usage
164 188
165### Production 189### Production
166 190
167If you want to run PeerTube for production (bad idea for now :) ): 191If you want to run PeerTube in production (which might be a bad idea for now :) ):
168 192
193```bash
169 $ cp config/production.yaml.example config/production.yaml 194 $ cp config/production.yaml.example config/production.yaml
195```
170 196
171Then edit the `config/production.yaml` file according to your webserver configuration. Keys set in this file will override those of `config/default.yml`. 197Then edit the `config/production.yaml` file according to your webserver
198configuration. Keys set in this file will override those of
199`config/default.yml`.
172 200
173Finally, run the server with the `production` `NODE_ENV` variable set. 201Finally, run the server with the `NODE_ENV` environment variable set to
202`production`:
174 203
204```bash
175 $ NODE_ENV=production npm start 205 $ NODE_ENV=production npm start
206```
176 207
177The administrator password is automatically generated and can be found in the logs. You can set another password with: 208The administrator password is automatically generated and can be found in the
209logs. You can set another password with:
178 210
211```bash
179 $ NODE_ENV=production npm run reset-password -- -u root 212 $ NODE_ENV=production npm run reset-password -- -u root
213```
180 214
181**Nginx template** (reverse proxy): https://github.com/Chocobozzz/PeerTube/tree/master/support/nginx <br /> 215**Nginx template** (reverse proxy): https://github.com/Chocobozzz/PeerTube/tree/master/support/nginx <br />
182**Systemd template**: https://github.com/Chocobozzz/PeerTube/tree/master/support/systemd 216**Systemd template**: https://github.com/Chocobozzz/PeerTube/tree/master/support/systemd
183 217
184You can check the application (CORS headers, tracker websocket...) by running: 218You can check the application (CORS headers, tracker websocket...) by running:
185 219
220```bash
186 $ NODE_ENV=production npm run check 221 $ NODE_ENV=production npm run check
222```
187 223
188### Upgrade 224### Upgrade
189 225
190The following commands will upgrade the source (according to your current branch), upgrade node modules and rebuild client application: 226The following commands will upgrade the source (according to your current
227branch), upgrade node modules and rebuild client application:
191 228
229```bash
192 # systemctl stop peertube 230 # systemctl stop peertube
193 $ npm run upgrade-peertube 231 $ npm run upgrade-peertube
194 # systemctl start peertube 232 # systemctl start peertube
233```
195 234
196### Development 235### Test with three fresh nodes
197
198In this mode, the server will run requests between instances more quickly, the video durations are limited to a few seconds.
199
200To develop on the server-side (server files are automatically compiled when we modify them and the server restarts automatically too):
201
202 $ npm run dev:server
203
204The server (with the client) will listen on `localhost:9000`.
205
206
207To develop on the client side (client files are automatically compiled when we modify them):
208
209 $ npm run dev:client
210
211The API will listen on `localhost:9000` and the frontend on `localhost:3000` (with hot module replacement, you don't need to refresh the web browser).
212
213**Username**: *root* <br/>
214**Password**: *test*
215
216### Test with 3 fresh nodes
217 236
237```bash
218 $ npm run clean:server:test 238 $ npm run clean:server:test
219 $ npm run play 239 $ npm run play
240```
220 241
221Then you will get access to the three nodes at `http://localhost:900{1,2,3}` with the `root` as username and `test{1,2,3}` for the password. 242Then you will get access to the three nodes at `http://localhost:900{1,2,3}`
243with the `root` as username and `test{1,2,3}` for the password.
222 244
223### Other commands 245### Other commands
224 246
225To print all available command run: 247To print all available commands, run:
226 248
249```bash
227 $ npm run help 250 $ npm run help
251```
228 252
229## Contributing 253## Contributing
230 254
231See the [contributing guide](https://github.com/Chocobozzz/PeerTube/blob/master/.github/CONTRIBUTING.md). 255See the [contributing
232 256guide](https://github.com/Chocobozzz/PeerTube/blob/master/.github/CONTRIBUTING.md)
233See the [server code documentation](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/server/code.md). 257to see how to contribute to PeerTube. Spoiler alert: you don't need to be a
234 258coder to help!
235See the [client code documentation](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/client/code.md).
236
237 259
238## Architecture 260## Architecture
239 261
240See [ARCHITECTURE.md](https://github.com/Chocobozzz/PeerTube/blob/master/ARCHITECTURE.md) for a more detailed explication. 262See [ARCHITECTURE.md](https://github.com/Chocobozzz/PeerTube/blob/master/ARCHITECTURE.md) for a more detailed explanation.
241 263
242### Backend 264### Backend
243 265
244 * The backend is a REST API 266 * The backend is a REST API.
245 * Servers communicate with each others with [Activity Pub](https://www.w3.org/TR/activitypub/) 267 * Servers communicate with each others with [Activity
246 * Each server has its own users who query it (search videos, where the torrent URI of this specific video is...) 268 Pub](https://www.w3.org/TR/activitypub/).
247 * If a user upload a video, the server seeds it and sends the video information (name, short description, torrent URI...) its followers 269 * Each server has its own users who query it (search videos, query where the
248 * A server is a tracker responsible for all the videos uploaded in it 270 torrent URI of this specific video is...).
249 * Even if nobody watches a video, it is seeded by the server (through [WebSeed protocol](http://www.bittorrent.org/beps/bep_0019.html)) where the video was uploaded 271 * If a user uploads a video, the server seeds it and sends its followers some
272 metadata (name, short description, torrent URI...).
273 * A server is a tracker responsible for all the videos uploaded in it.
274 * Even if nobody watches a video, it is seeded by the server (through
275 [WebSeed protocol](http://www.bittorrent.org/beps/bep_0019.html)) where the
276 video was uploaded.
250 277
251Here are some simple schemes: 278Here are some simple schemes:
252 279