support/doc/tools.md

   1 # CLI tools guide
   2
   3 [[toc]]
   4
   5 ## Remote PeerTube CLI
   6
   7 You need at least 512MB RAM to run the script.
   8 Scripts can be launched directly from a PeerTube server, or from a separate server, even a desktop PC.
   9 You 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
  13 Install the [PeerTube dependencies](/support/doc/dependencies.md) except PostgreSQL and Redis.
  14
  15 ### Installation
  16
  17 Clone the PeerTube repo to get the latest version (even if you are on your PeerTube server):
  18
  19 ```bash
  20 git clone https://github.com/Chocobozzz/PeerTube.git
  21 CLONE="$(pwd)/PeerTube"
  22 cd ${CLONE}
  23 ```
  24
  25 Install dependencies and build CLI tools:
  26
  27 ```bash
  28 NOCLIENT=1 yarn install --pure-lockfile
  29 npm run setup:cli
  30 ```
  31
  32 ### CLI wrapper
  33
  34 The wrapper provides a convenient interface to the following scripts.
  35 You 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
  37 ```
  38   Usage: peertube [command] [options]
  39
  40   Options:
  41
  42     -v, --version         output the version number
  43     -h, --help            output usage information
  44
  45   Commands:
  46
  47     auth [action]         register your accounts on remote instances to use them with other commands
  48     upload|up             upload a video
  49     import-videos|import  import a video from a streaming platform
  50     plugins|p [action]    manage instance plugins
  51     redundancy|r [action] manage video redundancies
  52     help [cmd]            display help for [cmd]
  53 ```
  54
  55 The wrapper can keep track of instances you have an account on. We limit to one account per instance for now.
  56
  57 ```bash
  58 peertube auth add -u 'PEERTUBE_URL' -U 'PEERTUBE_USER' --password 'PEERTUBE_PASSWORD'
  59 peertube auth list
  60 ┌──────────────────────────────┬──────────────────────────────┐
  61 │ instance                     │ login                        │
  62 ├──────────────────────────────┼──────────────────────────────┤
  63 │ 'PEERTUBE_URL'               │ 'PEERTUBE_USER'              │
  64 └──────────────────────────────┴──────────────────────────────┘
  65 ```
  66
  67 You can now use that account to upload videos without feeding the same parameters again.
  68
  69 ```bash
  70 peertube up <videoFile>
  71 ```
  72
  73 To list, install, uninstall dynamically plugins/themes of an instance:
  74
  75 ```bash
  76 peertube plugins list
  77 peertube plugins install --path /local/plugin/path
  78 peertube plugins install --npm-name peertube-plugin-myplugin
  79 peertube plugins uninstall --npm-name peertube-plugin-myplugin
  80 ```
  81
  82 #### peertube-import-videos.js
  83
  84 You can use this script to import videos from all [supported sites of youtube-dl](https://rg3.github.io/youtube-dl/supportedsites.html) into PeerTube.
  85 Be sure you own the videos or have the author's authorization to do so.
  86
  87 ```sh
  88 node dist/server/tools/peertube-import-videos.js \
  89     -u 'PEERTUBE_URL' \
  90     -U 'PEERTUBE_USER' \
  91     --password 'PEERTUBE_PASSWORD' \
  92     --target-url 'TARGET_URL'
  93 ```
  94
  95 * `PEERTUBE_URL` : the full URL of your PeerTube server where you want to import, eg: https://peertube.cpy.re
  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
 106 The script will get all public videos from Youtube, download them and upload to PeerTube.
 107 Already downloaded videos will not be uploaded twice, so you can run and re-run the script in case of crash, disconnection...
 108
 109 Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
 110
 111 **NB**: If you want to synchronize a Youtube channel to your PeerTube instance (ensure you have the agreement from the author),
 112 you can add a [crontab rule](https://help.ubuntu.com/community/CronHowto) (or an equivalent of your OS) and insert
 113 these rules (ensure to customize them to your needs):
 114
 115 ```
 116 # Update youtube-dl every day at midnight
 117 0 0 * * * /usr/bin/npm rebuild youtube-dl --prefix /PATH/TO/PEERTUBE/
 118
 119 # Synchronize the YT channel every sunday at 22:00 all the videos published since last monday included
 120 0 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)
 121 ```
 122
 123 Also you may want to subscribe to the PeerTube channel in order to manually check the synchronization is successful.
 124
 125 #### peertube-upload.js
 126
 127 You can use this script to import videos directly from the CLI.
 128
 129 Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
 130
 131 ```bash
 132 cd ${CLONE}
 133 node dist/server/tools/peertube-upload.js --help
 134 ```
 135
 136 #### peertube-plugins.js
 137
 138 Install/update/uninstall or list local or NPM PeerTube plugins:
 139
 140 ```bash
 141 cd ${CLONE}
 142 node dist/server/tools/peertube-plugins.js --help
 143 node dist/server/tools/peertube-plugins.js list --help
 144 node dist/server/tools/peertube-plugins.js install --help
 145 node dist/server/tools/peertube-plugins.js update --help
 146 node dist/server/tools/peertube-plugins.js uninstall --help
 147
 148 node dist/server/tools/peertube-plugins.js install --path /my/plugin/path
 149 node dist/server/tools/peertube-plugins.js install --npm-name peertube-theme-example
 150 ```
 151
 152 #### peertube-redundancy.js
 153
 154 Manage (list/add/remove) video redundancies:
 155
 156 To list your videos that are duplicated by remote instances:
 157
 158 ```bash
 159 node dist/server/tools/peertube.js redundancy list-remote-redundancies
 160 ```
 161
 162 To list remote videos that your instance duplicated:
 163
 164 ```bash
 165 node dist/server/tools/peertube.js redundancy list-my-redundancies
 166 ```
 167
 168 To duplicate a specific video in your redundancy system:
 169
 170 ```bash
 171 node dist/server/tools/peertube.js redundancy add --video 823
 172 ```
 173
 174 To remove a video redundancy:
 175
 176 ```bash
 177 node dist/server/tools/peertube.js redundancy remove --video 823
 178 ```
 179
 180 ## Server tools
 181
 182 These scripts should be run on the server, in `peertube-latest` directory.
 183
 184 ### parse-log
 185
 186 To parse PeerTube last log file:
 187
 188 ```bash
 189 # Basic installation
 190 cd /var/www/peertube/peertube-latest
 191 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run parse-log -- --level info
 192
 193 # Docker installation
 194 cd /var/www/peertube-docker
 195 docker-compose exec -u peertube peertube npm run parse-log -- --level info
 196 ```
 197
 198 `--level` is optional and could be `info`/`warn`/`error`
 199
 200 You can also remove SQL or HTTP logs using `--not-tags` (PeerTube >= 3.2):
 201
 202 ```bash
 203 # Basic installation
 204 cd /var/www/peertube/peertube-latest
 205 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run parse-log -- --level debug --not-tags http sql
 206
 207 # Docker installation
 208 cd /var/www/peertube-docker
 209 docker-compose exec -u peertube peertube npm run parse-log -- --level debug --not-tags http sql
 210 ```
 211
 212 ### regenerate-thumbnails.js
 213
 214 **PeerTube >= 3.2**
 215
 216 Regenerating local video thumbnails could be useful because new PeerTube releases may increase thumbnail sizes:
 217
 218 ```bash
 219 # Basic installation
 220 cd /var/www/peertube/peertube-latest
 221 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run regenerate-thumbnails
 222
 223 # Docker installation
 224 cd /var/www/peertube-docker
 225 docker-compose exec -u peertube peertube npm run regenerate-thumbnails
 226 ```
 227
 228 ### create-import-video-file-job.js
 229
 230 You can use this script to import a video file to replace an already uploaded file or to add a new webtorrent resolution to a video. PeerTube needs to be running.
 231 You can then create a transcoding job using the web interface if you need to optimize your file or create an HLS version of it.
 232
 233 ```bash
 234 # Basic installation
 235 cd /var/www/peertube/peertube-latest
 236 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
 237
 238 # Docker installation
 239 cd /var/www/peertube-docker
 240 docker-compose exec -u peertube peertube npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
 241 ```
 242
 243 ### create-move-video-storage-job.js
 244
 245 **PeerTube >= 4.0**
 246
 247 Use this script to move all video files or a specific video file to object storage.
 248
 249 ```bash
 250 # Basic installation
 251 cd /var/www/peertube/peertube-latest
 252 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-move-video-storage-job -- --to-object-storage -v [videoUUID]
 253
 254 # Docker installation
 255 cd /var/www/peertube-docker
 256 docker-compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-object-storage -v [videoUUID]
 257 ```
 258
 259 The script can also move all video files that are not already in object storage:
 260
 261 ```bash
 262 # Basic installation
 263 cd /var/www/peertube/peertube-latest
 264 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-move-video-storage-job -- --to-object-storage --all-videos
 265
 266 # Docker installation
 267 cd /var/www/peertube-docker
 268 docker-compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-object-storage --all-videos
 269 ```
 270
 271
 272 ### prune-storage.js
 273
 274 Some transcoded videos or shutdown at a bad time can leave some unused files on your storage.
 275 Stop PeerTube and delete these files (a confirmation will be demanded first):
 276
 277 ```bash
 278 cd /var/www/peertube/peertube-latest
 279 sudo systemctl stop peertube && sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage
 280 ```
 281
 282
 283 ### update-host.js
 284
 285 **Changing the hostname is unsupported and may be a risky operation, especially if you have already federated.**
 286 If you started PeerTube with a domain, and then changed it you will have
 287 invalid torrent files and invalid URLs in your database. To fix this, you have
 288 to run the command below (keep in mind your follower instances will NOT update their URLs).
 289
 290 ```bash
 291 # Basic installation
 292 cd /var/www/peertube/peertube-latest
 293 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run update-host
 294
 295 # Docker installation
 296 cd /var/www/peertube-docker
 297 docker-compose exec -u peertube peertube npm run update-host
 298 ```
 299
 300 ### reset-password.js
 301
 302 To reset a user password from CLI, run:
 303
 304 ```bash
 305 # Basic installation
 306 cd /var/www/peertube/peertube-latest
 307 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u target_username
 308
 309 # Docker installation
 310 cd /var/www/peertube-docker
 311 docker-compose exec -u peertube peertube npm run reset-password -- -u target_username
 312 ```
 313
 314
 315 ### plugin install/uninstall
 316
 317 The difference with `peertube plugins` CLI is that these scripts can be used even if PeerTube is not running.
 318 If 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).
 319
 320 To install/update a plugin or a theme from the disk:
 321
 322 ```bash
 323 cd /var/www/peertube/peertube-latest
 324 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:install -- --plugin-path /local/plugin/path
 325
 326 # Docker installation
 327 cd /var/www/peertube-docker
 328 docker-compose exec -u peertube peertube npm run plugin:install -- --plugin-path /local/plugin/path
 329 ```
 330
 331 From NPM:
 332
 333 ```bash
 334 cd /var/www/peertube/peertube-latest
 335 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:install -- --npm-name peertube-plugin-myplugin
 336
 337 # Docker installation
 338 cd /var/www/peertube-docker
 339 docker-compose exec -u peertube peertube npm run plugin:install -- --npm-name peertube-plugin-myplugin
 340 ```
 341
 342 To uninstall a plugin or a theme:
 343
 344 ```bash
 345 cd /var/www/peertube/peertube-latest
 346 sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin
 347
 348 # Docker installation
 349 cd /var/www/peertube-docker
 350 docker-compose exec -u peertube peertube npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin
 351 ```
 352
 353 ## PeerTube runner
 354
 355 PeerTube >= 5.2 supports VOD or Live transcoding by a remote PeerTube runner.
 356
 357
 358 ### Installation
 359
 360 ```bash
 361 sudo npm install -g @peertube/peertube-runner
 362 ```
 363
 364 ### Configuration
 365
 366 The runner uses env paths like `~/.config`, `~/.cache` and `~/.local/share` directories to store runner configuration or temporary files.
 367
 368 Multiple PeerTube runners can run on the same OS by using the `--id` CLI option (each runner uses its own config/tmp directories):
 369
 370 ```bash
 371 peertube-runner [commands] --id instance-1
 372 peertube-runner [commands] --id instance-2
 373 peertube-runner [commands] --id instance-3
 374 ```
 375
 376 You can change the runner configuration (jobs concurrency, ffmpeg threads/nice etc) by editing `~/.config/peertube-runner-nodejs/[id]/config.toml`.
 377
 378 ### Run the server
 379
 380 You need to run the runner in server mode first so it can run transcoding jobs of registered PeerTube instances:
 381
 382 ```bash
 383 peertube-runner server
 384 ```
 385
 386 ### Register
 387
 388 Then, you can register the runner on a new PeerTube instance so the runner can process its transcoding job:
 389
 390 ```bash
 391 peertube-runner register --url http://peertube.example.com --registration-token ptrrt-... --runner-name my-runner-name
 392 ```
 393
 394 The runner will then use a websocket connection with the PeerTube instance to be notified about new available transcoding jobs.
 395
 396 ### Unregister
 397
 398 To unregister a PeerTube instance:
 399
 400 ```bash
 401 peertube-runner unregister --url http://peertube.example.com --runner-name my-runner-name
 402 ```
 403
 404 ### List registered instances
 405
 406 ```bash
 407 peertube-runner list-registered
 408 ```