aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/tools.md
diff options
context:
space:
mode:
authorChocobozzz <me@florianbigard.com>2019-02-11 11:52:34 +0100
committerChocobozzz <me@florianbigard.com>2019-02-11 11:52:34 +0100
commit88108880bbdba473cfe36ecbebc1c3c4f972e102 (patch)
treeb242efb3b4f0d7e49d88f2d1f2063b5b3b0489c0 /support/doc/tools.md
parent53a94c7cfa8368da4cd248d65df8346905938f0c (diff)
parent9b712a2017e4ab3cf12cd6bd58278905520159d0 (diff)
downloadPeerTube-88108880bbdba473cfe36ecbebc1c3c4f972e102.tar.gz
PeerTube-88108880bbdba473cfe36ecbebc1c3c4f972e102.tar.zst
PeerTube-88108880bbdba473cfe36ecbebc1c3c4f972e102.zip
Merge branch 'develop' into pr/1217
Diffstat (limited to 'support/doc/tools.md')
-rw-r--r--support/doc/tools.md280
1 files changed, 221 insertions, 59 deletions
diff --git a/support/doc/tools.md b/support/doc/tools.md
index 1db29edc0..1a9ba7d2b 100644
--- a/support/doc/tools.md
+++ b/support/doc/tools.md
@@ -1,18 +1,66 @@
1# CLI tools guide 1# CLI tools guide
2 - [CLI wrapper](#cli-wrapper)
3 - [Remote tools](#remote-tools)
4 - [peertube-import-videos.js](#peertube-import-videosjs)
5 - [peertube-upload.js](#peertube-uploadjs)
6 - [peertube-watch.js](#peertube-watch)
7 - [Server tools](#server-tools)
8 - [parse-log](#parse-log)
9 - [create-transcoding-job.js](#create-transcoding-jobjs)
10 - [create-import-video-file-job.js](#create-import-video-file-jobjs)
11 - [prune-storage.js](#prune-storagejs)
12 2
13## CLI wrapper 3<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5**Table of Contents**
6
7- [Remote Tools](#remote-tools)
8 - [Dependencies](#dependencies)
9 - [Installation](#installation)
10 - [CLI wrapper](#cli-wrapper)
11 - [peertube-import-videos.js](#peertube-import-videosjs)
12 - [peertube-upload.js](#peertube-uploadjs)
13 - [peertube-watch.js](#peertube-watchjs)
14- [Server tools](#server-tools)
15 - [parse-log](#parse-log)
16 - [create-transcoding-job.js](#create-transcoding-jobjs)
17 - [create-import-video-file-job.js](#create-import-video-file-jobjs)
18 - [prune-storage.js](#prune-storagejs)
19 - [optimize-old-videos.js](#optimize-old-videosjs)
20 - [update-host.js](#update-hostjs)
21 - [REPL (Read Eval Print Loop)](#repl-read-eval-print-loop)
22 - [.help](#help)
23 - [Lodash example](#lodash-example)
24 - [YoutubeDL example](#youtubedl-example)
25 - [Models examples](#models-examples)
26
27<!-- END doctoc generated TOC please keep comment here to allow auto update -->
14 28
15The wrapper provides a convenient interface to most scripts, and requires the [same dependencies](#dependencies). You can access it as `peertube` via an alias in your `.bashrc` like `alias peertube="node ${PEERTUBE_PATH}/dist/server/tools/peertube.js"`: 29## Remote Tools
30
31You need at least 512MB RAM to run the script.
32Scripts can be launched directly from a PeerTube server, or from a separate server, even a desktop PC.
33You 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).
34
35### Dependencies
36
37Install the [PeerTube dependencies](dependencies.md).
38
39### Installation
40
41Clone the PeerTube repo to get the latest version (even if you are on your PeerTube server):
42
43```
44$ git clone https://github.com/Chocobozzz/PeerTube.git
45$ CLONE="$(pwd)/PeerTube"
46```
47
48Run ``yarn install --pure-lockfile``
49```
50$ cd ${CLONE}
51$ yarn install --pure-lockfile
52```
53
54Build server tools:
55```
56$ cd ${CLONE}
57$ npm run build:server
58```
59
60### CLI wrapper
61
62The wrapper provides a convenient interface to the following scripts.
63You 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):
16 64
17``` 65```
18 Usage: peertube [command] [options] 66 Usage: peertube [command] [options]
@@ -28,18 +76,19 @@ The wrapper provides a convenient interface to most scripts, and requires the [s
28 upload|up upload a video 76 upload|up upload a video
29 import-videos|import import a video from a streaming platform 77 import-videos|import import a video from a streaming platform
30 watch|w watch a video in the terminal ✩°。⋆ 78 watch|w watch a video in the terminal ✩°。⋆
79 repl initiate a REPL to access internals
31 help [cmd] display help for [cmd] 80 help [cmd] display help for [cmd]
32``` 81```
33 82
34The wrapper can keep track of instances you have an account on. We limit to one account per instance for now. 83The wrapper can keep track of instances you have an account on. We limit to one account per instance for now.
35 84
36```bash 85```bash
37$ peertube auth add -u "PEERTUBE_URL" -U "PEERTUBE_USER" --password "PEERTUBE_PASSWORD" 86$ peertube auth add -u 'PEERTUBE_URL' -U 'PEERTUBE_USER' --password 'PEERTUBE_PASSWORD'
38$ peertube auth list 87$ peertube auth list
39┌──────────────────────────────┬──────────────────────────────┐ 88┌──────────────────────────────┬──────────────────────────────┐
40│ instance │ login │ 89│ instance │ login │
41├──────────────────────────────┼──────────────────────────────┤ 90├──────────────────────────────┼──────────────────────────────┤
42"PEERTUBE_URL""PEERTUBE_USER" 91'PEERTUBE_URL''PEERTUBE_USER'
43└──────────────────────────────┴──────────────────────────────┘ 92└──────────────────────────────┴──────────────────────────────┘
44``` 93```
45 94
@@ -55,53 +104,22 @@ And now that your video is online, you can watch it from the confort of your ter
55$ peertube watch https://peertube.cpy.re/videos/watch/e8a1af4e-414a-4d58-bfe6-2146eed06d10 104$ peertube watch https://peertube.cpy.re/videos/watch/e8a1af4e-414a-4d58-bfe6-2146eed06d10
56``` 105```
57 106
58## Remote Tools 107#### peertube-import-videos.js
59
60You need at least 512MB RAM to run the script.
61Scripts can be launched directly from a PeerTube server, or from a separate server, even a desktop PC.
62You 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).
63
64### Dependencies
65
66Install the [PeerTube dependencies](dependencies.md).
67
68### Installation
69
70Clone the PeerTube repo to get the latest version (even if you are on your PeerTube server):
71
72```
73$ git clone https://github.com/Chocobozzz/PeerTube.git
74$ CLONE="$(pwd)/PeerTube"
75```
76
77Run ``yarn install``
78```
79$ cd ${CLONE}
80$ yarn install
81```
82
83Build server tools:
84```
85$ cd ${CLONE}
86$ npm run build:server
87```
88
89### peertube-import-videos.js
90 108
91You can use this script to import videos from all [supported sites of youtube-dl](https://rg3.github.io/youtube-dl/supportedsites.html) into PeerTube. 109You can use this script to import videos from all [supported sites of youtube-dl](https://rg3.github.io/youtube-dl/supportedsites.html) into PeerTube.
92Be sure you own the videos or have the author's authorization to do so. 110Be sure you own the videos or have the author's authorization to do so.
93 111
94```sh 112```sh
95$ node dist/server/tools/peertube-import-videos.js \ 113$ node dist/server/tools/peertube-import-videos.js \
96 -u "PEERTUBE_URL" \ 114 -u 'PEERTUBE_URL' \
97 -U "PEERTUBE_USER" \ 115 -U 'PEERTUBE_USER' \
98 --password "PEERTUBE_PASSWORD" \ 116 --password 'PEERTUBE_PASSWORD' \
99 -t "TARGET_URL" 117 -t 'TARGET_URL'
100``` 118```
101 119
102* `PEERTUBE_URL` : the full URL of your PeerTube server where you want to import, eg: https://peertube.cpy.re 120* `PEERTUBE_URL` : the full URL of your PeerTube server where you want to import, eg: https://peertube.cpy.re
103* `PEERTUBE_USER` : your PeerTube account where videos will be uploaded 121* `PEERTUBE_USER` : your PeerTube account where videos will be uploaded
104* `PEERTUBE_PASSWORD` : password of your PeerTube account (if omitted, you will be prompted for it) 122* `PEERTUBE_PASSWORD` : password of your PeerTube account (if `PEERTUBE_PASSWORD` is omitted, you will be prompted for it)
105* `TARGET_URL` : the target url you want to import. Examples: 123* `TARGET_URL` : the target url you want to import. Examples:
106 * YouTube: 124 * YouTube:
107 * Channel: https://www.youtube.com/channel/ChannelId 125 * Channel: https://www.youtube.com/channel/ChannelId
@@ -116,7 +134,7 @@ Already downloaded videos will not be uploaded twice, so you can run and re-run
116Videos will be publicly available after transcoding (you can see them before that in your account on the web interface). 134Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
117 135
118 136
119### peertube-upload.js 137#### peertube-upload.js
120 138
121You can use this script to import videos directly from the CLI. 139You can use this script to import videos directly from the CLI.
122 140
@@ -127,7 +145,7 @@ $ cd ${CLONE}
127$ node dist/server/tools/peertube-upload.js --help 145$ node dist/server/tools/peertube-upload.js --help
128``` 146```
129 147
130### peertube-watch.js 148#### peertube-watch.js
131 149
132You can use this script to play videos directly from the CLI. 150You can use this script to play videos directly from the CLI.
133 151
@@ -159,7 +177,7 @@ $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production
159 177
160### create-transcoding-job.js 178### create-transcoding-job.js
161 179
162You can use this script to force transcoding of an existing video. 180You can use this script to force transcoding of an existing video. PeerTube needs to be running.
163 181
164``` 182```
165$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-transcoding-job -- -v [videoUUID] 183$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-transcoding-job -- -v [videoUUID]
@@ -172,7 +190,7 @@ $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production
172 190
173### create-import-video-file-job.js 191### create-import-video-file-job.js
174 192
175You can use this script to import a video file to replace an already uploaded file or to add a new resolution to a video. 193You can use this script to import a video file to replace an already uploaded file or to add a new resolution to a video. PeerTube needs to be running.
176 194
177``` 195```
178$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile] 196$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
@@ -181,17 +199,161 @@ $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production
181### prune-storage.js 199### prune-storage.js
182 200
183Some transcoded videos or shutdown at a bad time can leave some unused files on your storage. 201Some transcoded videos or shutdown at a bad time can leave some unused files on your storage.
184To delete them (a confirmation will be demanded first): 202Stop PeerTube and delete these files (a confirmation will be demanded first):
185 203
186``` 204```
187$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage 205$ sudo systemctl stop peertube && sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage
188``` 206```
189 207
208### optimize-old-videos.js
209
210Before version v1.0.0-beta.16, Peertube did not specify a bitrate for the
211transcoding of uploaded videos. This means that videos might be encoded into
212very large files that are too large for streaming. This script re-transcodes
213these videos so that they can be watched properly, even on slow connections.
214
215```
216$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run optimize-old-videos
217```
218
219
190### update-host.js 220### update-host.js
191 221
192If you started PeerTube with a domain, and then changed it you will have invalid torrent files and invalid URLs in your database. 222If you started PeerTube with a domain, and then changed it you will have
193To fix this, you have to run: 223invalid torrent files and invalid URLs in your database. To fix this, you have
224to run:
194 225
195``` 226```
196$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run update-host 227$ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run update-host
197``` 228```
229
230### REPL ([Read Eval Print Loop](https://nodejs.org/docs/latest-v8.x/api/repl.html))
231
232If you want to interact with the application libraries and objects even when PeerTube is not running, there is a REPL for that.
233
234usage: `node ./dist/server/tools/peertube-repl.js`
235
236"The default evaluator will, by default, assign the result of the most recently evaluated expression to the special variable `_` (underscore). Explicitly setting `_` to a value will disable this behavior."
237
238- type `.help` to list commands available in the repl, notice it starts with a dot
239- type `.exit` to exit, note that you still have to press CTRL-C to actually exit, or press CTRL-C (3 times) without typing `.exit` to exit
240- type `context` to list all available objects and libraries in the context, note: `Promise` is also available but it's not listed in the context, in case you need promises for something
241- type `env` to see the loaded environment variables
242- type `path` to access path library
243- type `lodash` to access lodash library
244- type `uuidv1` to access uuid/v1 library
245- type `uuidv3` to access uuid/v3 library
246- type `uuidv4` to access uuid/v4 library
247- type `uuidv5` to access uuid/v5 library
248- type `YoutubeDL` to access youtube-dl library
249- type `cli` to access the cli helpers object
250- type `logger` to access the logger; if you log to it, it will write to stdout and to the peertube.log file
251- type `constants` to access the constants loaded by the server
252- type `coreUtils` to access the core-utils helpers object
253- type `ffmpegUtils` to access the ffmpeg-utils helpers object
254- type `peertubeCryptoUtils` to access the peertube-crypto helpers object
255- type `signupUtils` to access the signup helpers object
256- type `utils` to access the utils helpers object
257- type `YoutubeDLUtils` to access the youtube-dl helpers object
258- type `sequelizeTypescript` to access sequelizeTypescript
259- type `modelsUtils` to access the models/utils
260- type `models` to access the shortcut to sequelizeTypescript.models
261- type `transaction` to access the shortcut to sequelizeTypescript.transaction
262- type `query` to access the shortcut to sequelizeTypescript.query
263- type `queryInterface` to access the shortcut to sequelizeTypescript.queryInterface
264
265#### .help
266
267```
268PeerTube [1.0.0] (b10eb595)> .help
269.break Sometimes you get stuck, this gets you out
270.clear Break, and also clear the local context
271.editor Enter editor mode
272.exit Exit the repl
273.help Print this help message
274.load Load JS from a file into the REPL session
275.r Reset REPL
276.reset Reset REPL
277.save Save all evaluated commands in this REPL session to a file
278PeerTube [1.0.0] (b10eb595)>
279```
280
281#### Lodash example
282
283```
284PeerTube [1.0.0] (b10eb595)> lodash.keys(context)
285[ 'global',
286 'console',
287 'DTRACE_NET_SERVER_CONNECTION',
288 'DTRACE_NET_STREAM_END',
289 'DTRACE_HTTP_SERVER_REQUEST',
290 'DTRACE_HTTP_SERVER_RESPONSE',
291 'DTRACE_HTTP_CLIENT_REQUEST',
292 'DTRACE_HTTP_CLIENT_RESPONSE',
293 'process',
294 'Buffer',
295 'clearImmediate',
296 'clearInterval',
297 'clearTimeout',
298 'setImmediate',
299 'setInterval',
300 'setTimeout',
301 'XMLHttpRequest',
302 'compact2string',
303 'module',
304 'require',
305 'path',
306 'repl',
307 'context',
308 'env',
309 'lodash',
310 'uuidv1',
311 'uuidv3',
312 'uuidv4',
313 'uuidv5',
314 'cli',
315 'logger',
316 'constants',
317 'Sequelize',
318 'sequelizeTypescript',
319 'modelsUtils',
320 'models',
321 'transaction',
322 'query',
323 'queryInterface',
324 'YoutubeDL',
325 'coreUtils',
326 'ffmpegUtils',
327 'peertubeCryptoUtils',
328 'signupUtils',
329 'utils',
330 'YoutubeDLUtils' ]
331PeerTube [1.0.0] (b10eb595)>
332```
333
334#### YoutubeDL example
335```
336YoutubeDL.getInfo('https://www.youtube.com/watch?v=I5ZN289jjDo', function(err, data) {console.log(err, data)})
337```
338
339#### Models examples
340```
341PeerTube [1.0.0] (b10eb595)> new models.ActorModel({id: 3}).getVideoChannel().then(function(data){console.log(data.dataValues.name)})
342Promise {
343 _bitField: 0,
344 _fulfillmentHandler0: undefined,
345 _rejectionHandler0: undefined,
346 _promise0: undefined,
347 _receiver0: undefined }
348PeerTube [1.0.0] (b10eb595)> Main root channel
349PeerTube [1.0.0] (b10eb595)> let out; new models.UserModel({id: 1}).getAccount().then(function (data) {out = data.dataValues.id})
350Promise {
351 _bitField: 0,
352 _fulfillmentHandler0: undefined,
353 _rejectionHandler0: undefined,
354 _promise0: undefined,
355 _receiver0: undefined }
356PeerTube [1.0.0] (b10eb595)> out
3572
358PeerTube [1.0.0] (b10eb595)>
359```