aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/tools.md
diff options
context:
space:
mode:
authorChocobozzz <me@florianbigard.com>2023-07-31 14:34:36 +0200
committerChocobozzz <me@florianbigard.com>2023-08-11 15:02:33 +0200
commit3a4992633ee62d5edfbb484d9c6bcb3cf158489d (patch)
treee4510b39bdac9c318fdb4b47018d08f15368b8f0 /support/doc/tools.md
parent04d1da5621d25d59bd5fa1543b725c497bf5d9a8 (diff)
downloadPeerTube-3a4992633ee62d5edfbb484d9c6bcb3cf158489d.tar.gz
PeerTube-3a4992633ee62d5edfbb484d9c6bcb3cf158489d.tar.zst
PeerTube-3a4992633ee62d5edfbb484d9c6bcb3cf158489d.zip
Migrate server to ESM
Sorry for the very big commit that may lead to git log issues and merge conflicts, but it's a major step forward: * Server can be faster at startup because imports() are async and we can easily lazy import big modules * Angular doesn't seem to support ES import (with .js extension), so we had to correctly organize peertube into a monorepo: * Use yarn workspace feature * Use typescript reference projects for dependencies * Shared projects have been moved into "packages", each one is now a node module (with a dedicated package.json/tsconfig.json) * server/tools have been moved into apps/ and is now a dedicated app bundled and published on NPM so users don't have to build peertube cli tools manually * server/tests have been moved into packages/ so we don't compile them every time we want to run the server * Use isolatedModule option: * Had to move from const enum to const (https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums) * Had to explictely specify "type" imports when used in decorators * Prefer tsx (that uses esbuild under the hood) instead of ts-node to load typescript files (tests with mocha or scripts): * To reduce test complexity as esbuild doesn't support decorator metadata, we only test server files that do not import server models * We still build tests files into js files for a faster CI * Remove unmaintained peertube CLI import script * Removed some barrels to speed up execution (less imports)
Diffstat (limited to 'support/doc/tools.md')
-rw-r--r--support/doc/tools.md286
1 files changed, 111 insertions, 175 deletions
diff --git a/support/doc/tools.md b/support/doc/tools.md
index 2b3ebf159..40d9ec66a 100644
--- a/support/doc/tools.md
+++ b/support/doc/tools.md
@@ -4,59 +4,48 @@
4 4
5## Remote PeerTube CLI 5## Remote PeerTube CLI
6 6
7You need at least 512MB RAM to run the script. 7`peertube-cli` is a tool that communicates with a PeerTube instance using its [REST API](https://docs.joinpeertube.org/api-rest-reference.html).
8Scripts can be launched directly from a PeerTube server, or from a separate server, even a desktop PC. 8It can be launched from a remote server/computer to easily upload videos, manage plugins, redundancies etc.
9You need to follow all the following steps even if you are on a PeerTube server (including cloning the git repository in a different directory than your production installation because the scripts utilize non-production dependencies).
10
11### Dependencies
12
13Install the [PeerTube dependencies](/support/doc/dependencies.md) except PostgreSQL and Redis.
14 9
15### Installation 10### Installation
16 11
17Clone the PeerTube repo to get the latest version (even if you are on your PeerTube server): 12Ensure you have `node` installed on your system:
18 13
19```bash 14```bash
20git clone https://github.com/Chocobozzz/PeerTube.git 15node --version # Should be >= 16.x
21CLONE="$(pwd)/PeerTube"
22cd ${CLONE}
23``` 16```
24 17
25Install dependencies and build CLI tools: 18Then install the CLI:
26 19
27```bash 20```bash
28NOCLIENT=1 yarn install --pure-lockfile 21sudo npm install -g @peertube/peertube-cli
29npm run setup:cli
30``` 22```
31 23
32### CLI wrapper 24### CLI wrapper
33 25
34The wrapper provides a convenient interface to the following scripts. 26The wrapper provides a convenient interface to the following sub-commands.
35You can access it as `peertube` via an alias in your `.bashrc` like `alias peertube="cd /your/peertube/directory/ && node ./dist/server/tools/peertube.js"` (you have to keep the `cd` command):
36 27
37``` 28```
38 Usage: peertube [command] [options] 29Usage: peertube-cli [command] [options]
39
40 Options:
41 30
42 -v, --version output the version number 31Options:
43 -h, --help output usage information 32 -v, --version output the version number
33 -h, --help display help for command
44 34
45 Commands: 35Commands:
46 36 auth Register your accounts on remote instances to use them with other commands
47 auth [action] register your accounts on remote instances to use them with other commands 37 upload|up [options] Upload a video on a PeerTube instance
48 upload|up upload a video 38 redundancy|r Manage instance redundancies
49 import-videos|import import a video from a streaming platform 39 plugins|p Manage instance plugins/themes
50 plugins|p [action] manage instance plugins 40 get-access-token|token [options] Get a peertube access token
51 redundancy|r [action] manage video redundancies 41 help [command] display help for command
52 help [cmd] display help for [cmd]
53``` 42```
54 43
55The wrapper can keep track of instances you have an account on. We limit to one account per instance for now. 44The wrapper can keep track of instances you have an account on. We limit to one account per instance for now.
56 45
57```bash 46```bash
58peertube auth add -u 'PEERTUBE_URL' -U 'PEERTUBE_USER' --password 'PEERTUBE_PASSWORD' 47peertube-cli auth add -u 'PEERTUBE_URL' -U 'PEERTUBE_USER' --password 'PEERTUBE_PASSWORD'
59peertube auth list 48peertube-cli auth list
60┌──────────────────────────────┬──────────────────────────────┐ 49┌──────────────────────────────┬──────────────────────────────┐
61│ instance │ login │ 50│ instance │ login │
62├──────────────────────────────┼──────────────────────────────┤ 51├──────────────────────────────┼──────────────────────────────┤
@@ -64,124 +53,142 @@ peertube auth list
64└──────────────────────────────┴──────────────────────────────┘ 53└──────────────────────────────┴──────────────────────────────┘
65``` 54```
66 55
67You can now use that account to upload videos without feeding the same parameters again. 56You can now use that account to execute sub-commands without feeding the `--url`, `--username` and `--password` parameters:
68 57
69```bash 58```bash
70peertube up <videoFile> 59peertube-cli upload <videoFile>
60peertube-cli plugins list
61...
71``` 62```
72 63
73To list, install, uninstall dynamically plugins/themes of an instance: 64#### peertube-cli upload
65
66You can use this script to upload videos directly from the CLI.
67
68Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
74 69
75```bash 70```bash
76peertube plugins list 71cd ${CLONE}
77peertube plugins install --path /local/plugin/path 72peertube-cli upload --help
78peertube plugins install --npm-name peertube-plugin-myplugin
79peertube plugins uninstall --npm-name peertube-plugin-myplugin
80``` 73```
81 74
82#### peertube-import-videos.js 75#### peertube-cli plugins
76
77Install/update/uninstall or list local or NPM PeerTube plugins:
83 78
84You can use this script to import videos from all [supported sites of youtube-dl](https://rg3.github.io/youtube-dl/supportedsites.html) into PeerTube. 79```bash
85Be sure you own the videos or have the author's authorization to do so. 80cd ${CLONE}
81peertube-cli plugins --help
82peertube-cli plugins list --help
83peertube-cli plugins install --help
84peertube-cli plugins update --help
85peertube-cli plugins uninstall --help
86 86
87```sh 87peertube-cli plugins install --path /my/plugin/path
88node dist/server/tools/peertube-import-videos.js \ 88peertube-cli plugins install --npm-name peertube-theme-example
89 -u 'PEERTUBE_URL' \
90 -U 'PEERTUBE_USER' \
91 --password 'PEERTUBE_PASSWORD' \
92 --target-url 'TARGET_URL'
93``` 89```
94 90
95* `PEERTUBE_URL` : the full URL of your PeerTube server where you want to import, eg: https://peertube.cpy.re 91#### peertube-cli redundancy
96* `PEERTUBE_USER` : your PeerTube account where videos will be uploaded
97* `PEERTUBE_PASSWORD` : password of your PeerTube account (if `--password PEERTUBE_PASSWORD` is omitted, you will be prompted for it)
98* `TARGET_URL` : the target url you want to import. Examples:
99 * YouTube:
100 * Channel: https://www.youtube.com/channel/ChannelId
101 * User https://www.youtube.com/c/UserName or https://www.youtube.com/user/UserName
102 * Video https://www.youtube.com/watch?v=blabla
103 * Vimeo: https://vimeo.com/xxxxxx
104 * Dailymotion: https://www.dailymotion.com/xxxxx
105 92
106The script will get all public videos from Youtube, download them and upload to PeerTube. 93Manage (list/add/remove) video redundancies:
107Already downloaded videos will not be uploaded twice, so you can run and re-run the script in case of crash, disconnection...
108 94
109Videos will be publicly available after transcoding (you can see them before that in your account on the web interface). 95To list your videos that are duplicated by remote instances:
96
97```bash
98peertube-cli redundancy list-remote-redundancies
99```
110 100
111**NB**: If you want to synchronize a Youtube channel to your PeerTube instance (ensure you have the agreement from the author), 101To list remote videos that your instance duplicated:
112you can add a [crontab rule](https://help.ubuntu.com/community/CronHowto) (or an equivalent of your OS) and insert
113these rules (ensure to customize them to your needs):
114 102
103```bash
104peertube-cli redundancy list-my-redundancies
105```
106
107To duplicate a specific video in your redundancy system:
108
109```bash
110peertube-cli redundancy add --video 823
115``` 111```
116# Update youtube-dl every day at midnight
1170 0 * * * /usr/bin/npm rebuild youtube-dl --prefix /PATH/TO/PEERTUBE/
118 112
119# Synchronize the YT channel every sunday at 22:00 all the videos published since last monday included 113To remove a video redundancy:
1200 22 * * 0 /usr/bin/node /PATH/TO/PEERTUBE/dist/server/tools/peertube-import-videos.js -u '__PEERTUBE_URL__' -U '__USER__' --password '__PASSWORD__' --target-url 'https://www.youtube.com/channel/___CHANNEL__' --since $(date --date="-6 days" +\%Y-\%m-\%d) 114
115```bash
116peertube-cli redundancy remove --video 823
121``` 117```
122 118
123Also you may want to subscribe to the PeerTube channel in order to manually check the synchronization is successful.
124 119
125#### peertube-upload.js 120## PeerTube runner
126 121
127You can use this script to import videos directly from the CLI. 122PeerTube >= 5.2 supports VOD or Live transcoding by a remote PeerTube runner.
128 123
129Videos will be publicly available after transcoding (you can see them before that in your account on the web interface). 124### Installation
125
126Ensure you have `node`, `ffmpeg` and `ffprobe` installed on your system:
130 127
131```bash 128```bash
132cd ${CLONE} 129node --version # Should be >= 16.x
133node dist/server/tools/peertube-upload.js --help 130ffprobe -version # Should be >= 4.3
131ffmpeg -version # Should be >= 4.3
134``` 132```
135 133
136#### peertube-plugins.js 134Then install the CLI:
137
138Install/update/uninstall or list local or NPM PeerTube plugins:
139 135
140```bash 136```bash
141cd ${CLONE} 137sudo npm install -g @peertube/peertube-runner
142node dist/server/tools/peertube-plugins.js --help 138```
143node dist/server/tools/peertube-plugins.js list --help 139
144node dist/server/tools/peertube-plugins.js install --help 140### Configuration
145node dist/server/tools/peertube-plugins.js update --help 141
146node dist/server/tools/peertube-plugins.js uninstall --help 142The runner uses env paths like `~/.config`, `~/.cache` and `~/.local/share` directories to store runner configuration or temporary files.
143
144Multiple PeerTube runners can run on the same OS by using the `--id` CLI option (each runner uses its own config/tmp directories):
147 145
148node dist/server/tools/peertube-plugins.js install --path /my/plugin/path 146```bash
149node dist/server/tools/peertube-plugins.js install --npm-name peertube-theme-example 147peertube-runner [commands] --id instance-1
148peertube-runner [commands] --id instance-2
149peertube-runner [commands] --id instance-3
150``` 150```
151 151
152#### peertube-redundancy.js 152You can change the runner configuration (jobs concurrency, ffmpeg threads/nice etc) by editing `~/.config/peertube-runner-nodejs/[id]/config.toml`.
153 153
154Manage (list/add/remove) video redundancies: 154### Run the server
155 155
156To list your videos that are duplicated by remote instances: 156You need to run the runner in server mode first so it can run transcoding jobs of registered PeerTube instances:
157 157
158```bash 158```bash
159node dist/server/tools/peertube.js redundancy list-remote-redundancies 159peertube-runner server
160``` 160```
161 161
162To list remote videos that your instance duplicated: 162### Register
163
164Then, you can register the runner to process transcoding job of a remote PeerTube instance:
163 165
164```bash 166```bash
165node dist/server/tools/peertube.js redundancy list-my-redundancies 167peertube-runner register --url http://peertube.example.com --registration-token ptrrt-... --runner-name my-runner-name
166``` 168```
167 169
168To duplicate a specific video in your redundancy system: 170The runner will then use a websocket connection with the PeerTube instance to be notified about new available transcoding jobs.
171
172### Unregister
173
174To unregister a PeerTube instance:
169 175
170```bash 176```bash
171node dist/server/tools/peertube.js redundancy add --video 823 177peertube-runner unregister --url http://peertube.example.com --runner-name my-runner-name
172``` 178```
173 179
174To remove a video redundancy: 180### List registered instances
175 181
176```bash 182```bash
177node dist/server/tools/peertube.js redundancy remove --video 823 183peertube-runner list-registered
178``` 184```
179 185
180## Server tools 186## Server tools
181 187
182These scripts should be run on the server, in `peertube-latest` directory. 188Server tools are scripts that interect directly with the code of your PeerTube instance.
189They must be run on the server, in `peertube-latest` directory.
183 190
184### parse-log 191### Parse logs
185 192
186To parse PeerTube last log file: 193To parse PeerTube last log file:
187 194
@@ -209,9 +216,7 @@ cd /var/www/peertube-docker
209docker-compose exec -u peertube peertube npm run parse-log -- --level debug --not-tags http sql 216docker-compose exec -u peertube peertube npm run parse-log -- --level debug --not-tags http sql
210``` 217```
211 218
212### regenerate-thumbnails.js 219### Regenerate video thumbnails
213
214**PeerTube >= 3.2**
215 220
216Regenerating local video thumbnails could be useful because new PeerTube releases may increase thumbnail sizes: 221Regenerating local video thumbnails could be useful because new PeerTube releases may increase thumbnail sizes:
217 222
@@ -225,7 +230,7 @@ cd /var/www/peertube-docker
225docker-compose exec -u peertube peertube npm run regenerate-thumbnails 230docker-compose exec -u peertube peertube npm run regenerate-thumbnails
226``` 231```
227 232
228### create-import-video-file-job.js 233### Add or replace specific video file
229 234
230You can use this script to import a video file to replace an already uploaded file or to add a new web compatible resolution to a video. PeerTube needs to be running. 235You can use this script to import a video file to replace an already uploaded file or to add a new web compatible resolution to a video. PeerTube needs to be running.
231You can then create a transcoding job using the web interface if you need to optimize your file or create an HLS version of it. 236You can then create a transcoding job using the web interface if you need to optimize your file or create an HLS version of it.
@@ -240,9 +245,7 @@ cd /var/www/peertube-docker
240docker-compose exec -u peertube peertube npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile] 245docker-compose exec -u peertube peertube npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
241``` 246```
242 247
243### create-move-video-storage-job.js 248### Move video files to object storage
244
245**PeerTube >= 4.0**
246 249
247Use this script to move all video files or a specific video file to object storage. 250Use this script to move all video files or a specific video file to object storage.
248 251
@@ -269,7 +272,7 @@ docker-compose exec -u peertube peertube npm run create-move-video-storage-job -
269``` 272```
270 273
271<!-- TODO: uncomment when PeerTube 6 is released 274<!-- TODO: uncomment when PeerTube 6 is released
272### create-generate-storyboard-job 275### Generate storyboard
273 276
274**PeerTube >= 6.0** 277**PeerTube >= 6.0**
275 278
@@ -298,7 +301,7 @@ docker-compose exec -u peertube peertube npm run create-generate-storyboard-job
298``` 301```
299--> 302-->
300 303
301### prune-storage.js 304### Prune filesystem storage
302 305
303Some transcoded videos or shutdown at a bad time can leave some unused files on your storage. 306Some transcoded videos or shutdown at a bad time can leave some unused files on your storage.
304Stop PeerTube and delete these files (a confirmation will be demanded first): 307Stop PeerTube and delete these files (a confirmation will be demanded first):
@@ -308,8 +311,7 @@ cd /var/www/peertube/peertube-latest
308sudo systemctl stop peertube && sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage 311sudo systemctl stop peertube && sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage
309``` 312```
310 313
311 314### Update PeerTube instance domain name
312### update-host.js
313 315
314**Changing the hostname is unsupported and may be a risky operation, especially if you have already federated.** 316**Changing the hostname is unsupported and may be a risky operation, especially if you have already federated.**
315If you started PeerTube with a domain, and then changed it you will have 317If you started PeerTube with a domain, and then changed it you will have
@@ -326,7 +328,7 @@ cd /var/www/peertube-docker
326docker-compose exec -u peertube peertube npm run update-host 328docker-compose exec -u peertube peertube npm run update-host
327``` 329```
328 330
329### reset-password.js 331### Reset user password
330 332
331To reset a user password from CLI, run: 333To reset a user password from CLI, run:
332 334
@@ -341,7 +343,7 @@ docker-compose exec -u peertube peertube npm run reset-password -- -u target_use
341``` 343```
342 344
343 345
344### plugin install/uninstall 346### Install or uninstall plugins
345 347
346The difference with `peertube plugins` CLI is that these scripts can be used even if PeerTube is not running. 348The difference with `peertube plugins` CLI is that these scripts can be used even if PeerTube is not running.
347If PeerTube is running, you need to restart it for the changes to take effect (whereas with `peertube plugins` CLI, plugins/themes are dynamically loaded on the server). 349If PeerTube is running, you need to restart it for the changes to take effect (whereas with `peertube plugins` CLI, plugins/themes are dynamically loaded on the server).
@@ -378,69 +380,3 @@ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production np
378cd /var/www/peertube-docker 380cd /var/www/peertube-docker
379docker-compose exec -u peertube peertube npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin 381docker-compose exec -u peertube peertube npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin
380``` 382```
381
382## PeerTube runner
383
384PeerTube >= 5.2 supports VOD or Live transcoding by a remote PeerTube runner.
385
386
387### Installation
388
389Ensure you have `ffmpeg` and `ffprobe` installed on your system:
390
391```bash
392ffprobe -version # Should be >= 4.3
393ffmpeg -version # Should be >= 4.3
394```
395
396Then install the CLI:
397
398```bash
399sudo npm install -g @peertube/peertube-runner
400```
401
402### Configuration
403
404The runner uses env paths like `~/.config`, `~/.cache` and `~/.local/share` directories to store runner configuration or temporary files.
405
406Multiple PeerTube runners can run on the same OS by using the `--id` CLI option (each runner uses its own config/tmp directories):
407
408```bash
409peertube-runner [commands] --id instance-1
410peertube-runner [commands] --id instance-2
411peertube-runner [commands] --id instance-3
412```
413
414You can change the runner configuration (jobs concurrency, ffmpeg threads/nice etc) by editing `~/.config/peertube-runner-nodejs/[id]/config.toml`.
415
416### Run the server
417
418You need to run the runner in server mode first so it can run transcoding jobs of registered PeerTube instances:
419
420```bash
421peertube-runner server
422```
423
424### Register
425
426Then, you can register the runner to process transcoding job of a remote PeerTube instance:
427
428```bash
429peertube-runner register --url http://peertube.example.com --registration-token ptrrt-... --runner-name my-runner-name
430```
431
432The runner will then use a websocket connection with the PeerTube instance to be notified about new available transcoding jobs.
433
434### Unregister
435
436To unregister a PeerTube instance:
437
438```bash
439peertube-runner unregister --url http://peertube.example.com --runner-name my-runner-name
440```
441
442### List registered instances
443
444```bash
445peertube-runner list-registered
446```