OpenCloud
/
PeerTube
mirror of https://github.com/Chocobozzz/PeerTube
1
0
Fork 0
Code Issues Releases Wiki Activity

Try to improve documentations/readme

pull/200/head
Chocobozzz 2018-01-12 18:07:41 +01:00
parent 339632b4a3
commit 63bfad7ec9
No known key found for this signature in database
GPG Key ID: 583A612D890159BE
12 changed files with 335 additions and 374 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
.github/CONTRIBUTING.md vendored
View File

@ -1,14 +1,12 @@
# Welcome to the contributing guide for PeerTube
Interesting in contributing? Awesome :)
Interesting in contributing? Awesome!
**Quick Links:**
* [Give your feedback](#give-your-feedback)
* [Develop on the Server side](#develop-on-the-server-side)
* [Develop on the Client side](#develop-on-the-client-side)
* [Get started with development](#get-started-with-development)
* [Write documentation](#write-documentation)
* [Develop](#develop)
## Give your feedback
@ -16,40 +14,32 @@ Interesting in contributing? Awesome :)
You don't need to know how to code to start contributing to PeerTube! Other
contributions are very valuable too, among which: you can test the software and
report bugs, you can give feedback on potential bugs, features that you are
interested in, user interace, design, decentralized architecture...
interested in, user interface, design, decentralized architecture...
## Development
## Write documentation
## Develop on the Server side
You can help to write the documentation of the REST API, code, architecture,
demonstrations...
The server is a web server developed with
[NodeJS](https://nodejs.org)/[Express](http://expressjs.com).
Newcomer? You can find a documentation of the server code/architecture
[here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/server/code.md).
## Develop
Don't hesitate to talk about features you want to develop by creating an issue
before you start working on them :).
## Develop on the Client side
The client is a web application developed with
[TypeScript](https://www.typescriptlang.org/)/[Angular2](https://angular.io/).
Newcomer? You can find a documentation of the server code/architecture
[here](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/client/code.md).
## Get started with development
In this mode, the server will run requests between instances more quickly, the
video durations are limited to a few seconds.
### Prerequisites
First, make sure that you have followed the steps to install the dependencies.
First, make sure that you have followed
[the steps](/support/doc/dependencies.md)
to install the dependencies.
Then clone the sources and install node modules:
```bash
$ git clone -b master https://github.com/Chocobozzz/PeerTube
$ cd PeerTube
$ yarn install --pure-lockfile
```
Then, create a postgres database and user with the values set in the
`config/default.yaml` file. For instance, if you do not change the values
@ -57,40 +47,51 @@ there, the following commands would create a new database called `peertube_dev`
and a postgres user called `peertube` with password `peertube`:
```bash
# sudo -u postgres createuser -P peertube
Enter password for new role: peertube
# sudo -u postgres createdb -O peertube peertube_dev
# sudo -u postgres createuser -P peertube
Enter password for new role: peertube
# sudo -u postgres createdb -O peertube peertube_dev
```
In dev mode, administrator username is **root** and password is **test**.
### Server side
You can find a documentation of the server code/architecture [here](/support/doc/development/server/code.md).
To develop on the server-side:
```bash
$ npm run dev:server
$ npm run dev:server
```
Then, the server will listen on `localhost:9000`. When server source files
change, these are automatically recompiled and the server will automatically
restart.
restart. Server is in `TEST` mode so it will run requests between instances more quickly.
### Client side
You can find a documentation of the server code/architecture
[here](/support/doc/development/client/code.md).
To develop on the client side:
```bash
$ npm run dev:client
$ npm run dev:client
```
The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
Client files are automatically compiled on change, and the web browser will
reload them automatically thanks to hot module replacement.
**Username**: *root* <br/>
**Password**: *test*
### Test federation
This will run 3 nodes:
## Write documentation
```bash
$ npm run clean:server:test
$ npm run play
```
You can help to write the documentation of the REST API, code, architecture,
demonstrations...
Then 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.

23
.github/ISSUE_TEMPLATE.md vendored
View File

@ -1,10 +1,15 @@
<!--
Problem with the demonstration server?
-> Please retry in a few hours or send me directly an email: https://github.com/Chocobozzz
Bug?
-> Please check first you're running on the latest version of Firefox/Chromium
-> Please check the console log to add informations to the bug report
-->
<!-- If you report a bug please fill the form -->
* **PeerTube version or commit:**
* **Browser name/version:**
* **NodeJS version:**
* **PostgreSQL version:**
* **What is the expected behaviour?**
* **What do you see instead?**
* **Browser console log if useful (Gist/Pastebin...):**
* **Server log if useful (Gist/Pastebin...):**
* Browser name/version:
* Console log if useful (Gist/Pastebin...):

2
ARCHITECTURE.md
View File

@ -18,7 +18,7 @@
* 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).
directory](/shared/models/activitypub).
* All the requests are retried several times if they fail.
### Instance

4
FAQ.md
View File

@ -31,9 +31,9 @@ We think it is acceptable for a video platform.
WEBM, MP4 or OGV videos.
## I want to change my host or move to HTTPS, how can I do that?
## I want to change my host, how can I do that?
If you already have followers, you can't.
If you don't have any followers, update your configuration and run
`NODE_ENV=production npm run update-host` to update the torrent files.
`NODE_ENV=production npm run update-host` to update the torrent files (they contain your domain name).

150
README.md
View File

@ -64,13 +64,12 @@ donating them](https://soutenir.framasoft.org/en/).**
Want to see it in action?
* [Demo server](http://peertube.cpy.re)
* Demonstration servers:
* [peertube.cpy.re](http://peertube.cpy.re)
* [peertube2.cpy.re](http://peertube2.cpy.re)
* [peertube3.cpy.re](http://peertube3.cpy.re)
* [Video](https://peertube.cpy.re/videos/watch/f78a97f8-a142-4ce1-a5bd-154bf9386504)
to see how the "decentralization feature" looks like
* 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.
## Why
@ -83,12 +82,11 @@ So we need to have a decentralized network of servers seeding videos (as
enough because one video could become famous and overload the server. It's the
reason why we need to use a P2P protocol to limit the server load. Thanks to
[WebTorrent](https://github.com/feross/webtorrent), we can make P2P (thus
bittorrent) inside the web browser, as of today.
BitTorrent) inside the web browser, as of today.
## Features
- [X] Frontend
- [X] Angular frontend
- [X] Angular frontend
- [X] Join the fediverse
- [X] Follow other instances
- [X] Unfollow an instance
@ -103,8 +101,8 @@ bittorrent) inside the web browser, as of today.
- [X] OpenGraph tags
- [X] OEmbed
- [X] Update video
- [X] Videos view counter
- [X] Videos likes/dislikes
- [X] Federated videos view counter
- [X] Federated videos likes/dislikes
- [X] Transcoding to different definitions
- [X] Download file/torrent
- [X] User video bytes quota
@ -115,140 +113,32 @@ bittorrent) inside the web browser, as of today.
- [X] User registration
- [X] Video privacy settings (public, unlisted or private)
- [X] Signaling a video to the admin origin PeerTube instance
- [ ] Videos comments
- [X] Federated videos comments
- [ ] Video imports (URL, Torrent, YouTube...)
- [ ] Advanced search
- [ ] Subtitles
- [ ] User playlist
- [ ] User subscriptions (by tags, author...)
- [ ] Add "DDOS" security
## Installation
## Front compatibility
See [wiki](https://github.com/Chocobozzz/PeerTube/wiki) for complete
installation commands.
* Firefox
* Chrome/Chromium
### Front compatibility
* Chromium
* Firefox (>= 42 for MediaSource support)
### Dependencies
## Dependencies
* nginx
* PostgreSQL
* **NodeJS >= 8.x**
* yarn
* OpenSSL (cli)
* PostgreSQL
* FFmpeg
#### Debian
## Production
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)
2. Install yarn:
[https://yarnpkg.com/en/docs/install](https://yarnpkg.com/en/docs/install)
4. Run:
```bash
$ apt-get update
$ apt-get install ffmpeg postgresql openssl
```
#### Ubuntu 16.04
1. Install NodeJS 8.x (current LTS): (same as Debian)
2. Install yarn: (same as Debian)
3. Run:
```bash
$ apt-get update
$ apt-get install ffmpeg postgresql openssl
```
#### Arch Linux
1. Run:
```bash
$ pacman -S nodejs yarn ffmpeg postgresql openssl
```
#### Other distributions
Feel free to update this README file in a pull request!
### Build from the sources
```bash
$ git clone -b master https://github.com/Chocobozzz/PeerTube
$ cd PeerTube
$ yarn install
$ npm run build
```
## Usage
### Production
If you want to run PeerTube in production (which might be a bad idea for now :) ):
```bash
$ cp config/production.yaml.example config/production.yaml
```
Then edit the `config/production.yaml` file according to your webserver
configuration. Keys set in this file will override those of
`config/default.yml`.
Finally, run the server with the `NODE_ENV` environment variable set to
`production`:
```bash
$ NODE_ENV=production npm start
```
The administrator password is automatically generated and can be found in the
logs. You can set another password with:
```bash
$ NODE_ENV=production npm run reset-password -- -u root
```
**Nginx template** (reverse proxy): https://github.com/Chocobozzz/PeerTube/tree/master/support/nginx <br />
**Systemd template**: https://github.com/Chocobozzz/PeerTube/tree/master/support/systemd
You can check the application (CORS headers, tracker websocket...) by running:
```bash
$ NODE_ENV=production npm run check
```
### Upgrade
The following commands will upgrade the source (according to your current
branch), upgrade node modules and rebuild client application:
```bash
# systemctl stop peertube
$ npm run upgrade-peertube
# systemctl start peertube
```
### Test with three fresh nodes
```bash
$ npm run clean:server:test
$ npm run play
```
Then 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.
### Other commands
To print all available commands, run:
```bash
$ npm run help
```
See the [production guide](support/doc/production.md).
## Contributing

1
package.json
View File

@ -34,7 +34,6 @@
"dev:server": "scripty",
"dev:client": "scripty",
"start": "node dist/server",
"check": "ts-node ./scripts/check.ts",
"upgrade-peertube": "scripty",
"upgrade": "echo 'This command was renamed to upgrade-peertube.'",
"update-host": "ts-node ./scripts/update-host.ts",

171
scripts/check.ts
View File

@ -1,171 +0,0 @@
import * as series from 'async/series'
import * as request from 'request'
import * as WebSocket from 'ws'
import { CONFIG } from '../server/initializers/constants'
const requestHeaders = {
'Range': '',
'Keep-Alive': '',
'User-Agent': 'Mozilla',
'Cache-Control': 'no-cache',
'Content-Type': '',
'Host': 'example.com',
'Access-Control-Request-Method': 'GET',
'Access-Control-Request-Headers': 'range'
}
series([
pingServer,
checkCORSTorrent,
checkCORSWebSeed,
checkTracker
], function () {
process.exit(0)
})
// ---------------------------------------------------------------------------
function pingServer (callback: () => void) {
const pingUrl = CONFIG.WEBSERVER.URL + '/api/v1/ping'
console.log('Checking server is up (%s)...', pingUrl)
request(pingUrl, function (err, res, body) {
if (!err && res.statusCode === 200 && body === 'pong') {
console.log('SUCCESS.')
} else {
console.log('FAIL.')
}
callback()
})
}
function checkCORSTorrent (callback: () => void) {
const torrentUrl = CONFIG.WEBSERVER.URL + '/static/torrents/test.torrent'
console.log('Checking CORS headers for the torrent (%s)...', torrentUrl)
request({
method: 'OPTIONS',
uri: torrentUrl,
headers: requestHeaders
}, function (err, res) {
if (err || isThereValidCORSHeaders(res) === false) {
console.error('FAIL.')
} else {
console.log('SUCCESS.')
}
callback()
})
}
function checkCORSWebSeed (callback: () => void) {
const webseedUrl = CONFIG.WEBSERVER.URL + '/static/webseed/test.mp4'
console.log('Checking CORS headers for the video (%s)...', webseedUrl)
request({
method: 'OPTIONS',
uri: webseedUrl,
headers: requestHeaders
}, function (err, res) {
if (err || isThereValidCORSHeaders(res) === false) {
console.error('FAIL.')
} else {
console.log('SUCCESS.')
}
callback()
})
}
function checkTracker (callback: () => void) {
const trackerUrl = CONFIG.WEBSERVER.WS + '://' +
CONFIG.WEBSERVER.HOST +
'/tracker/socket'
console.log('Checking tracker websocket (%s)...', trackerUrl)
let ws = null
ws = new WebSocket(trackerUrl)
const timeout = setTimeout(failed, 1000)
ws.on('open', onOpen)
function onOpen () {
clearTimeout(timeout)
ws.close()
console.log('SUCCESS.')
callback()
}
function failed () {
ws.removeListener('open', onOpen)
ws.close()
console.log('FAILED.')
callback()
}
}
function isThereValidCORSHeaders (res: request.RequestResponse) {
let fail = false
// Check Access-Control-Allow-Origin
const headerAllowOriginKey = 'access-control-allow-origin'
const headerAllowOrigin = res.headers[headerAllowOriginKey]
if (!headerAllowOrigin) {
console.error(headerAllowOriginKey + ' is not present.')
fail = true
} else if (headerAllowOrigin !== '*') {
console.error(headerAllowOriginKey + ' does not equal "*".')
fail = true
}
// Check Access-Control-Allow-Methods
const headerAllowMethodsKey = 'access-control-allow-methods'
const headerAllowMethods = res.headers[headerAllowMethodsKey]
if (!headerAllowMethods) {
console.error(headerAllowMethodsKey + ' is not present.')
fail = true
} else {
const allowMethodsMissed = findPatternNotInString(headerAllowMethods as string, [ 'get' ])
if (allowMethodsMissed !== null) {
console.error(headerAllowMethodsKey + ' misses the ' + allowMethodsMissed + ' method.')
fail = true
}
}
// Check Access-Control-Allow-Headers
const headerAllowHeadersKey = 'access-control-allow-headers'
const headerAllowHeaders = res.headers[headerAllowHeadersKey]
if (!headerAllowHeaders) {
console.error(headerAllowHeadersKey + ' is not present.')
fail = true
} else {
const headersThatShouldBePresent = [
'Range'
]
const allowHeadersMissed = findPatternNotInString(headerAllowHeaders as string, headersThatShouldBePresent)
if (allowHeadersMissed !== null) {
console.error(headerAllowHeadersKey + ' misses the ' + allowHeadersMissed + ' header.')
fail = true
}
}
return !fail
}
function findPatternNotInString (stringChain: string, patterns: string[]) {
let res = null
const stringChainLowerCase = stringChain.toLowerCase()
patterns.forEach(function (pattern) {
if (stringChainLowerCase.indexOf(pattern.toLowerCase()) === -1) {
res = pattern
}
})
return res
}

29
support/doc/dependencies.md Normal file
View File

@ -0,0 +1,29 @@
# Installation
## Dependencies
### Debian / Ubuntu
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)
2. Install yarn:
[https://yarnpkg.com/en/docs/install](https://yarnpkg.com/en/docs/install)
4. Run:
```bash
$ apt-get update
$ apt-get install nginx ffmpeg postgresql openssl g++ make
```
### Arch Linux
1. Run:
```bash
$ pacman -S nodejs yarn ffmpeg postgresql openssl
```
### Other distributions
Feel free to update this file in a pull request!

7
support/doc/development/client/code.md
View File

@ -53,12 +53,7 @@ Details of the Angular application file structure. It tries to follow [the offic
Uses [TSLint](https://palantir.github.io/tslint/) for TypeScript linting and [Angular styleguide](https://angular.io/docs/ts/latest/guide/style-guide.html).
## Developing
* Install [the dependencies](https://github.com/Chocobozzz/PeerTube#dependencies)
* Run `yarn install --pure-lockfile` at the root directory to install all the dependencies
* Run PostgreSQL and create the database `peertube_dev`.
* Run `npm run dev:client` to compile the client, run the server, watch client files modifications and reload modules on the fly (you don't need to refresh manually the web browser). The API listen on `localhost:9000` and the client on `localhost:3000`.
## Concepts
In a Angular application, we create components that we put together. Each component is defined by an HTML structure, a TypeScript file and optionally a SASS file.
If you are not familiar with Angular I recommend you to read the [quickstart guide](https://angular.io/docs/ts/latest/quickstart.html).

15
support/doc/development/server/code.md
View File

@ -36,21 +36,6 @@ All other server files are in the [server](https://github.com/Chocobozzz/PeerTub
Uses [JavaScript Standard Style](http://standardjs.com/).
## Developing
* Install [the dependencies](https://github.com/Chocobozzz/PeerTube#dependencies)
* Run `yarn install` at the root directory to install all the dependencies
* Run PostgreSQL and create the database `peertube_dev`.
* Run `npm run dev:server` to run the server, watch server files modifications and restart it automatically. The server (API + client) listen on `localhost:9000`.
The `NODE_ENV=test` is set to speed up communications between instances (see [constants.ts](https://github.com/Chocobozzz/PeerTube/blob/master/server/initializers/constants.ts)).
`npm run help` gives you all available commands.
If you want to test the decentralization feature, you can easily run 3 instances by running `npm run play`. The instances password are `test1`, `test2` and `test3`.
## Architecture
The server is composed by:

227
support/doc/production.md Normal file
View File

@ -0,0 +1,227 @@
# Production guide
## Installation
### Dependencies
Follow the steps of the [dependencies guide](dependencies.md).
### PeerTube user
Create a `peertube` user with `/home/peertube` home:
```bash
sudo useradd -m -d /home/peertube -s /bin/bash -p peertube peertube
sudo passwd peertube
```
### Database
Create production database and peertube user:
```bash
sudo -u postgres createuser -P peertube
sudo -u postgres createdb -O peertube peertube_prod
```
### Sources
Clone, install node dependencies and build application:
```bash
$ cd /home/peertube
$ sudo -u peertube git clone -b master https://github.com/Chocobozzz/PeerTube
$ cd PeerTube
$ sudo -u peertube yarn install --pure-lockfile
$ sudo -u peertube npm run build
```
### PeerTube configuration
Copy example configuration:
```bash
$ sudo -u peertube cp config/production.yaml.example config/production.yaml
```
Then edit the `config/production.yaml` file according to your webserver
configuration. Keys set in this file will override those of
`config/default.yml`.
### Webserver
Copy the nginx configuration template:
```bash
$ sudo cp /home/peertube/PeerTube/support/nginx/peertube-https /etc/nginx/sites-available/peertube
```
Then modify the webserver configuration file. Please pay attention to the `alias` key of `/static/webseed` location.
It should correspond to the path of your videos directory (set in the configuration file as `storage->videos` key).
```bash
$ sudo vim /etc/nginx/sites-available/peertube
```
If you want to set https with Let's Encrypt please follow the steps of [this guide](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04).
An example of the nginx configuration could be:
```
server {
listen 80;
listen [::]:80;
server_name peertube.example.com;
access_log /var/log/nginx/peertube.example.com.access.log;
error_log /var/log/nginx/peertube.example.com.error.log;
rewrite ^ https://$server_name$request_uri? permanent;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name peertube.example.com;
# For example with Let's Encrypt
ssl_certificate /etc/letsencrypt/live/peertube.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/peertube.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/peertube.example.com/chain.pem;
access_log /var/log/nginx/peertube.example.com.access.log;
error_log /var/log/nginx/peertube.example.com.error.log;
location ^~ '/.well-known/acme-challenge' {
default_type "text/plain";
root /var/www/certbot;
}
location / {
proxy_pass http://localhost:9000;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# For the video upload
client_max_body_size 8G;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;
}
# Bypass PeerTube webseed route for better performances
location /static/webseed {
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'Range,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
add_header 'Access-Control-Max-Age' 1728000;
add_header 'Content-Type' 'text/plain charset=UTF-8';
add_header 'Content-Length' 0;
return 204;
}
if ($request_method = 'GET') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'Range,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
}
alias /var/www/PeerTube/videos;
}
# Websocket tracker
location /tracker/socket {
# Peers send a message to the tracker every 15 minutes
# Don't close the websocket before this time
proxy_read_timeout 1200s;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
proxy_pass http://localhost:9000;
}
}
```
Activate the configuration file:
```bash
$ sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
$ sudo systemctl reload nginx
```
### Systemd
Copy the nginx configuration template:
```bash
sudo cp /home/peertube/PeerTube/support/systemd/peertube.service /etc/systemd/system/
```
Update the service file:
```bash
sudo vim /etc/systemd/system/peertube.service
```
It should look like this:
```
[Unit]
Description=PeerTube daemon
After=network.target
[Service]
Type=simple
Environment=NODE_ENV=production
User=peertube
Group=peertube
ExecStart=/usr/bin/npm start
WorkingDirectory=/home/peertube/PeerTube
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=peertube
Restart=always
[Install]
WantedBy=multi-user.target
```
Tell systemd to reload its config:
```bash
sudo systemctl daemon-reload
```
### Run
```bash
sudo systemctl start peertube
sudo journalctl -feu peertube
```
### Administrator
The administrator password is automatically generated and can be found in the
logs. You can set another password with:
```bash
$ NODE_ENV=production npm run reset-password -- -u root
```
## Upgrade
The following commands will upgrade the source (according to your current
branch), upgrade node modules and rebuild client application:
```bash
# systemctl stop peertube
$ npm run upgrade-peertube
# systemctl start peertube
```

1
support/systemd/peertube.service
View File

@ -1,5 +1,6 @@
[Unit]
Description=PeerTube daemon
After=network.target
[Service]
Type=simple