# Technical Documentation: Chocobozzz/PeerTube
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Chocobozzz/PeerTube)
### Overview (`README.md`)
Website
| Join an instance
| Create an instance
| Chat with us
| Donate
Be part of a network of multiple small federated, interoperable video hosting providers. Follow video creators and create videos. No vendor lock-in. All on a platform that is community-owned and ad-free.
Developed with ❤ by Framasoft
Introduction
----------------------------------------------------------------
PeerTube is a free, decentralized and federated video platform developed as an alternative to other platforms that centralize our data and attention, such as YouTube, Dailymotion or Vimeo. :clapper:
To learn more:
* This [two-minute video](https://framatube.org/videos/watch/217eefeb-883d-45be-b7fc-a788ad8507d3) (hosted on PeerTube) explaining what PeerTube is and how it works
* PeerTube's project homepage, [joinpeertube.org](https://joinpeertube.org)
* Demonstration instances:
* [peertube.cpy.re](https://peertube.cpy.re) (stable)
* [peertube2.cpy.re](https://peertube2.cpy.re) (Nightly)
* [peertube3.cpy.re](https://peertube3.cpy.re) (RC)
* This [video](https://peertube.cpy.re/videos/watch/da2b08d4-a242-4170-b32a-4ec8cbdca701) demonstrating the communication between PeerTube and [Mastodon](https://github.com/tootsuite/mastodon) (a decentralized Twitter alternative)
:sparkles: Features
----------------------------------------------------------------
All features for viewers
| All features for content creators
| All features for administrators
Video streaming, even in live!
Just upload your videos, and be sure they will stream anywhere. Add a description, some tags and your video will be discoverable by the entire video fediverse, not just your instance. You can even embed a player on your favorite website!
You are used to hosting live events? We got you covered too! Start livestreaming from your favorite client, and even host permanent streams!
---
Keep in touch with video creators
Follow your favorite channels from PeerTube or really any other place. No need to have an account on the instance you watched a video to follow its author, you can do all of that from the Fediverse (Mastodon, Pleroma, and plenty others), or just with good ol' RSS.
---
An interface to call home
Be it as a user or an instance administrator, you can decide what your experience will be like. Don't like the colors? They are easy to change. Don't want to list videos of an instance but let your users subscribe to them? Don't like the regular web client? All of that can be changed, and much more. No UX dark pattern, no mining your data, no video recommendation bullshit™.
---
Communities that help each other
In addition to visitors using P2P with WebRTC to share the load among them, instances can help each other by caching one another's videos. This way even small instances have a way to show content to a wider audience, as they will be shouldered by friend instances (more about that in our redundancy guide).
Content creators can get help from their viewers in the simplest way possible: a support button showing a message linking to their donation accounts or really anything else. No more pay-per-view and advertisements that hurt visitors and alter creativity (more about that in our FAQ).
:raised_hands: Contributing
----------------------------------------------------------------
You don't need to be a programmer to help!
You can give us your feedback, report bugs, help us translate PeerTube, write documentation, and more. Check out the [contributing
guide](https://docs.joinpeertube.org/contribute/getting-started) to know how, it takes less than 2 minutes to get started. :wink:
You can also join the cheerful bunch that makes our community:
* Matrix (bridged on [Discord](https://discord.gg/wj8DDUT)): **[#peertube:matrix.org](https://matrix.to/#/#peertube:matrix.org)**
* Forum: [https://framacolibri.org/c/peertube](https://framacolibri.org/c/peertube)
Feel free to reach out if you have any questions or ideas! :speech_balloon:
:package: Create your own instance
----------------------------------------------------------------
See the [production guide](https://docs.joinpeertube.org/install/any-os), which is the recommended way to install or upgrade PeerTube. For hardware requirements, see [Should I have a big server to run PeerTube?](https://joinpeertube.org/faq#should-i-have-a-big-server-to-run-peertube) in the FAQ.
See the [community packages](https://docs.joinpeertube.org/install/unofficial), which cover various platforms (including [YunoHost](https://install-app.yunohost.org/?app=peertube) and [Docker](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/docker.md)).
:book: Documentation
----------------------------------------------------------------
If you have a question, please try to find the answer in the [FAQ](https://joinpeertube.org/faq) first.
### User documentation
See the [user documentation](https://docs.joinpeertube.org/use/setup-account).
### Admin documentation
See [how to create your own instance](https://github.com/Chocobozzz/PeerTube/blob/develop/README.md#package-create-your-own-instance).
See the more general [admin documentation](https://docs.joinpeertube.org/admin/following-instances).
### Tools documentation
Learn how to import/upload videos from CLI or admin your PeerTube instance with the [tools documentation](https://docs.joinpeertube.org/maintain/tools).
### Technical documentation
See the [architecture blueprint](https://docs.joinpeertube.org/contribute/architecture) for a more detailed explanation of the architectural choices.
See our REST API documentation:
* OpenAPI 3.0.0 schema: [/support/doc/api/openapi.yaml](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/api/openapi.yaml)
* Spec explorer: [docs.joinpeertube.org/api-rest-reference.html](https://docs.joinpeertube.org/api-rest-reference.html)
See our [ActivityPub documentation](https://docs.joinpeertube.org/api/activitypub).
## License
### Logo
[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/), by [Framasoft](https://framasoft.org)
### Code
Copyright (C) 2015-2025 PeerTube Contributors (see [CREDITS.md](/CREDITS.md))
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see .
---
### Overview (`apps/peertube-cli/README.md`)
# PeerTube CLI
## Usage
See https://docs.joinpeertube.org/maintain/tools#remote-tools
## Dev
## Install dependencies
```bash
cd peertube-root
npm run install-node-dependencies
```
## Develop
```bash
cd peertube-root
npm run dev:peertube-cli
```
## Build
```bash
cd peertube-root
npm run build:peertube-cli
```
## Run
```bash
cd peertube-root
node apps/peertube-cli/dist/peertube.js --help
```
## Publish on NPM
```bash
cd peertube-root
(cd apps/peertube-cli && npm version patch) && npm run build:peertube-cli && (cd apps/peertube-cli && npm login && npm publish --access=public)
```
---
### Overview (`apps/peertube-runner/README.md`)
# PeerTube runner
Runner program to execute jobs (transcoding...) of remote PeerTube instances.
Commands below has to be run at the root of PeerTube git repository.
## Dev
### Install dependencies
```bash
cd peertube-root
npm run install-node-dependencies
```
### Develop
```bash
cd peertube-root
npm run dev:peertube-runner
```
### Build
```bash
cd peertube-root
npm run build:peertube-runner
```
### Run
```bash
cd peertube-root
node apps/peertube-runner/dist/peertube-runner.mjs --help
```
### Publish on NPM
```bash
cd peertube-root
(cd apps/peertube-runner && npm version patch) && npm run build:peertube-runner && (cd apps/peertube-runner && npm login && npm publish --access=public)
```
---
### Overview (`packages/transcription-devtools/README.md`)
# Transcription DevTools
Includes:
* __JiWER__ CLI NodeJS wrapper
* Benchmark tool to test multiple transcription engines
* TypeScript classes to evaluate word-error-rate of files generated by the transcription
## Build
```sh
npm run build
```
## Benchmark
A benchmark of available __transcribers__ might be run with:
```sh
npm run benchmark
```
```
┌────────────────────────┬───────────────────────┬───────────────────────┬──────────┬────────┬───────────────────────┐
│ (index) │ WER │ CER │ duration │ model │ engine │
├────────────────────────┼───────────────────────┼───────────────────────┼──────────┼────────┼───────────────────────┤
│ 5yZGBYqojXe7nuhq1TuHvz │ '28.39506172839506%' │ '9.62457337883959%' │ '41s' │ 'tiny' │ 'openai-whisper' │
│ x6qREJ2AkTU4e5YmvfivQN │ '29.75206611570248%' │ '10.46195652173913%' │ '15s' │ 'tiny' │ 'whisper-ctranslate2' │
└────────────────────────┴───────────────────────┴───────────────────────┴──────────┴────────┴───────────────────────┘
```
The benchmark may be run with multiple model builtin sizes:
```sh
MODELS=tiny,small,large npm run benchmark
```
## Jiwer
> *JiWER is a python tool for computing the word-error-rate of ASR systems.*
> https://jitsi.github.io/jiwer/cli/
__JiWER__ serves as a reference implementation to calculate errors rates between 2 text files:
- WER (Word Error Rate)
- CER (Character Error Rate)
### Usage
```typescript
const jiwerCLI = new JiwerClI('./reference.txt', './hypothesis.txt')
// WER as a percentage, ex: 0.03 -> 3%
console.log(await jiwerCLI.wer())
// CER as a percentage: 0.01 -> 1%
console.log(await jiwerCLI.cer())
// Detailed comparison report
console.log(await jiwerCLI.alignment())
```
## Resources
- https://jitsi.github.io/jiwer/
- https://github.com/rapidfuzz/RapidFuzz
---
### Overview (`packages/transcription/README.md`)
# Transcription
Video **transcription** consists in transcribing the audio content of a video to a text.
> This process might be called __Automatic Speech Recognition__ or __Speech to Text__ in more general context.
Provide a common API to many transcription backend, currently:
- `openai-whisper` CLI
- `faster-whisper` (*via* `whisper-ctranslate2` CLI)
> Potential candidates could be: whisper-cpp, vosk, ...
## Requirements
- Python 3
- PIP
And at least one of the following transcription backend:
- Python:
- `openai-whisper`
- `whisper-ctranslate2>=0.4.3`
## Usage
Create a transcriber manually:
```typescript
import { OpenaiTranscriber } from '@peertube/peertube-transcription'
(async () => {
// Optional if you want to use a local installation of transcribe engines
const binDirectory = 'local/pip/path/bin'
// Create a transcriber powered by OpenAI Whisper CLI
const transcriber = new OpenaiTranscriber({
name: 'openai-whisper',
command: 'whisper',
languageDetection: true,
binDirectory
});
// If not installed globally, install the transcriber engine (use pip under the hood)
await transcriber.install('local/pip/path')
// Transcribe
const transcriptFile = await transcriber.transcribe({
mediaFilePath: './myVideo.mp4',
model: 'tiny',
format: 'txt'
});
console.log(transcriptFile.path);
console.log(await transcriptFile.read());
})();
```
Using a local model file:
```typescript
import { WhisperBuiltinModel } from '@peertube/peertube-transcription/dist'
const transcriptFile = await transcriber.transcribe({
mediaFilePath: './myVideo.mp4',
model: await WhisperBuiltinModel.fromPath('./models/large.pt'),
format: 'txt'
});
```
You may use the builtin Factory if you're happy with the default configuration:
```Typescript
import { transcriberFactory } from '@peertube/peertube-transcription'
transcriberFactory.createFromEngineName({
engineName: transcriberName,
logger: compatibleWinstonLogger,
transcriptDirectory: '/tmp/transcription'
})
```
> For further usage [../tests/src/transcription/whisper/transcriber/openai-transcriber.spec.ts](../tests/src/transcription/whisper/transcriber/openai-transcriber.spec.ts)
## Lexicon
- ONNX: Open Neural Network eXchange. A specification, the ONNX Runtime run these models.
- GPTs: Generative Pre-Trained Transformers
- LLM: Large Language Models
- NLP: Natural Language Processing
- MLP: Multilayer Perceptron
- ASR: Automatic Speech Recognition
- WER: Word Error Rate
- CER: Character Error Rate
---
### Overview (`packages/types-generator/README.md`)
# PeerTube typings
These **Typescript** *types* are mainly used to write **PeerTube** plugins.
## Installation
Npm:
```
npm install --save-dev @peertube/peertube-types
```
## Usage
> See [contribute-plugins](https://docs.joinpeertube.org/contribute/plugins#typescript) **Typescript** section of the doc.
---
### Overview (`client/src/standalone/embed-player-api/README.md`)
# @peertube/embed-api
See https://docs.joinpeertube.org/api/embed-player
---
### Support Doc Api Quickstart (`support/doc/api/quickstart.md`)
# REST API quick start
## Detect a PeerTube instance
There are several ways to know if a website uses the PeerTube software:
* The server exposes NodeInfo information: https://peertube2.cpy.re/nodeinfo/2.0.json
* The server sends a `x-powered-by: PeerTube` header response to API requests
* HTML pages include a `` tag
## Authentication
### Get client
Some endpoints need authentication. We use OAuth 2.0 so first fetch the client tokens:
::: code-group
```bash [Curl]
curl https://peertube.example.com/api/v1/oauth-clients/local
```
```js [JS]
const { client_id, client_secret } = await fetch('https://peertube.example.com/api/v1/oauth-clients/local', {
headers: { 'Content-Type': 'application/json' }
}).then(res => res.json())
```
:::
Response example:
```json
{
"client_id": "v1ikx5hnfop4mdpnci8nsqh93c45rldf",
"client_secret": "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt"
}
```
### Get user token
Now you can fetch the user token:
::: code-group
```bash [Curl]
curl -X POST \
-d "client_id=v1ikx5hnfop4mdpnci8nsqh93c45rldf&client_secret=AjWiOapPltI6EnsWQwlFarRtLh4u8tDt&grant_type=password&response_type=code&username=your_user&password=your_password" \
https://peertube.example.com/api/v1/users/token
```
```js [JS]
const { access_token } = await fetch('https://peertube.example.com/api/v1/users/token', {
contentType: 'application/x-www-form-urlencoded',
method: 'POST',
body: new URLSearchParams({
client_id: '...',
client_secret: '...',
username: '...',
password: '...',
grant_type: 'password'
})
}).then(res => res.json())
```
:::
Response example:
```json
{
"access_token": "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0",
"token_type": "Bearer",
"expires_in": 14399,
"refresh_token": "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7"
}
```
Just use the `access_token` in the `Authorization` header:
```bash
curl -H 'Authorization: Bearer 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0' https://peertube.example.com/api/v1/jobs/completed
```
## List videos
```bash
curl https://peertube.example.com/api/v1/videos
```
## Libraries
Convenience libraries can be generated automatically from the [OpenAPI specification](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/api/openapi.yaml) for [languages supported by the OpenAPI generator](https://openapi-generator.tech/docs/generators/#client-generators).
---
### Support Doc Dependencies (`support/doc/dependencies.md`)
# Dependencies
:warning: **Warning**: dependencies guide is maintained by the community. Some parts may be outdated! :warning:
Main dependencies supported by PeerTube:
* `node` LTS (**>= 22.22 and <25**)
* `pnpm` >= 12.x
* `postgres` >=14.x
* `redis-server` >=6.2
* `ffmpeg` >=4.3 (using a ffmpeg static build [is not recommended](https://github.com/Chocobozzz/PeerTube/issues/6308))
* `python` >=3.8
* `pip`
_note_: only **LTS** versions of external dependencies are supported. If no LTS version matching the version constraint is available, only **release** versions are supported.
_note_: some distributions still ship a PostgreSQL older than 14 in their default repositories. Check with `psql --version` after
installing, and if it is too old, install a supported release from the
[PostgreSQL official repositories](https://www.postgresql.org/download/) instead of the distribution package.
[[toc]]
## Debian / Ubuntu and derivatives
1. On a fresh Debian/Ubuntu, as root user, install basic utility programs needed for the installation
```sh
sudo apt-get install curl sudo unzip vim
```
1. It would be wise to disable root access and to continue this tutorial with a user with sudoers group access. You can see a guide for how to do this in Debian/Ubuntu [here](https://www.digitalocean.com/community/tutorials/how-to-add-and-delete-users-on-ubuntu-20-04).
1. Install NodeJS 22.x: https://nodesource.com/products/distributions
1. Install [PNPM](https://pnpm.io/fr/installation):
```sh
sudo npm install pnpm
```
1. Install Python:
```sh
sudo apt update
sudo apt install python3-dev python3-pip python-is-python3
python --version # Should be >= 3.8
```
1. Install common dependencies:
```sh
sudo apt update
sudo apt install certbot nginx ffmpeg postgresql postgresql-contrib openssl g++ make redis-server git cron wget
ffmpeg -version # Should be >= 4.1
g++ -v # Should be >= 5.x
redis-server --version # Should be >= 6.x
psql --version # Should be >= 14
```
Debian 11 (bullseye) and Ubuntu 20.04 ship PostgreSQL 13 or older: on these releases install PostgreSQL from the
[PostgreSQL APT repository](https://www.postgresql.org/download/linux/ubuntu/) instead.
Now that dependencies are installed, before running PeerTube you should start PostgreSQL and Redis:
```sh
sudo systemctl start redis postgresql
```
## Arch Linux
Run:
```sh
sudo pacman -S nodejs-lts-iron ffmpeg postgresql openssl redis git wget unzip python python-pip base-devel npm nginx pnpm
```
Now that dependencies are installed, before running PeerTube you should start PostgreSQL and Redis:
```sh
sudo systemctl start redis postgresql
```
## CentOS 7
1. Install NodeJS 22.x: https://nodesource.com/products/distributions
1. Install [PNPM](https://pnpm.io/fr/installation):
```sh
sudo npm install pnpm
````
1. Install or compile ffmpeg:
* Install - [https://linoxide.com/linux-how-to/install-ffmpeg-centos-7/](https://linoxide.com/linux-how-to/install-ffmpeg-centos-7/)
* Compile - [https://gist.github.com/mustafaturan/7053900#file-latest-ffmpeg-centos6-sh](https://gist.github.com/mustafaturan/7053900#file-latest-ffmpeg-centos6-sh)
1. Install Packages:
```sh
sudo yum update
sudo yum install epel-release centos-release-scl
sudo yum update
sudo yum install nginx postgresql postgresql-server postgresql-contrib openssl gcc-c++ make wget redis git devtoolset-7
```
:warning: The CentOS 7 base repository provides PostgreSQL 9.2, which is too old for PeerTube. Install PostgreSQL >= 14 from
the [PostgreSQL Yum repository](https://www.postgresql.org/download/linux/redhat/) instead of the `postgresql*` packages above.
1. You need to use a more up to date version of G++ in order to run the `npm run install-node-dependencies` command, hence the installation of devtoolset-7.
```sh
sudo scl enable devtoolset-7 bash
```
Later when you invoke any node command, please prefix them with `CC=/opt/rh/devtoolset-7/root/usr/bin/gcc CXX=/opt/rh/devtoolset-7/root/usr/bin/g++`, such as with:
```sh
sudo -H -u peertube CC=/opt/rh/devtoolset-7/root/usr/bin/gcc CXX=/opt/rh/devtoolset-7/root/usr/bin/g++ npm run install-node-dependencies -- --production
```
1. Initialize the PostgreSQL database:
```sh
sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
```
Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis:
```sh
sudo systemctl enable --now redis
sudo systemctl enable --now postgresql
```
## Centos 8
1. Install NodeJS 22.x: https://nodesource.com/products/distributions
1. Install [PNPM](https://pnpm.io/fr/installation):
```sh
sudo npm install pnpm
````
1. Install or compile ffmpeg:
```sh
sudo dnf install epel-release dnf-utils
sudo yum-config-manager --set-enabled powertools
sudo yum-config-manager --add-repo=https://negativo17.org/repos/epel-multimedia.repo
sudo dnf install ffmpeg
```
1. Install packages:
```sh
sudo dnf update
sudo dnf install epel-release
sudo dnf update
sudo dnf module enable postgresql:16 # Default stream is PostgreSQL 10, too old for PeerTube
sudo dnf install nginx postgresql postgresql-server postgresql-contrib openssl gcc-c++ make wget redis git unzip
psql --version # Should be >= 14
```
Use `sudo dnf module list postgresql` to see the streams available on your release, and pick the most recent one >= 14.
1. You'll need a symlink for python3 to python for youtube-dl to work
```sh
sudo ln -s /usr/bin/python3 /usr/bin/python
```
1. Initialize the PostgreSQL database:
```sh
sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
```
Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis:
```sh
sudo systemctl enable --now redis
sudo systemctl enable --now postgresql
```
## Rocky Linux 8.4
1. Pull the latest updates:
```sh
sudo dnf update -y
```
1. Install NodeJS 22.x:
```sh
sudo dnf module install -y nodejs:22
```
1. Install PNPM:
```sh
sudo npm install pnpm
```
1. Install or compile ffmpeg (if you want to compile... enjoy):
```sh
sudo dnf install -y epel-release
sudo dnf --enablerepo=powertools install -y SDL2 SDL2-devel
sudo dnf install -y --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-8.noarch.rpm
sudo dnf install -y ffmpeg
sudo dnf update -y
```
1. Install PostgreSQL and Python3 and other stuff:
```sh
sudo dnf module enable -y postgresql:16 # Default stream is PostgreSQL 10, too old for PeerTube
sudo dnf install -y nginx postgresql postgresql-server postgresql-contrib openssl gcc-c++ make wget redis git python3 python3-pip
psql --version # Should be >= 14
sudo ln -s /usr/bin/python3 /usr/bin/python
sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
sudo systemctl enable --now redis
sudo systemctl enable --now postgresql
```
1. Unknown missing steps:
- Steps missing here... these were adapted from the CentOS 8 steps which abruptly ended.
- /var/www/peertube does not exist yet (expected? done in future steps? documentation?).
- Nothing about Certbot, NGINX, Firewall settings, and etc.
- Hopefully someone can suggest what is missing here with some hints so I can add it?
## Fedora
1. Upgrade your packages:
```sh
dnf upgrade
```
1. (Optional) Install certbot (choose instructions for your distribution):
[https://certbot.eff.org/all-instructions](https://certbot.eff.org/all-instructions)
1. Install NodeJS 22.x: https://nodesource.com/products/distributions
1. Install PNPM:
```sh
sudo npm install pnpm
```
1. Enable [RPM Fusion](https://rpmfusion.org) for Fedora (available for x86, x86_64, armhfp)
```sh
sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
```
This is necessary because `ffmpeg` is not in the Fedora repos.
1. Run:
```sh
sudo dnf install nginx ffmpeg postgresql-server postgresql-contrib openssl gcc-c++ make redis git vim
ffmpeg -version # Should be >= 4.1
g++ -v # Should be >= 5.x
redis-server --version # Should be >= 6.x
```
1. Configure nginx
```sh
sudo mkdir /etc/nginx/sites-available
sudo mkdir /etc/nginx/sites-enabled
sudo ln -s /etc/nginx/sites-enabled/peertube /etc/nginx/conf.d/peertube.conf
```
1. Post-installation
_from [PostgreSQL documentation](https://www.postgresql.org/download/linux/redhat/):_
> Due to policies for Red Hat family distributions, the PostgreSQL installation will not be enabled for automatic start or have the database initialized automatically.
```sh
# PostgreSQL
sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
sudo systemctl enable postgresql.service
sudo systemctl start postgresql.service
# Nginx
sudo systemctl enable nginx.service
sudo systemctl start nginx.service
# Redis
sudo systemctl enable redis.service
sudo systemctl start redis.service
```
1. Firewall
By default, you cannot access your server via public IP. To do so, you must configure the firewall.
Ports used by peertube dev setup:
```sh
sudo firewall-cmd --permanent --zone=public --add-port=3000/tcp
sudo firewall-cmd --permanent --zone=public --add-port=9000/tcp
```
* Optional
```sh
sudo firewall-cmd --permanent --zone=public --add-service=http
sudo firewall-cmd --permanent --zone=public --add-service=https
```
* Reload firewall
```sh
sudo firewall-cmd --reload
```
1. Configure max ports
This is necessary if you are running dev setup, otherwise you will have errors with `nodemon`
```sh
echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
```
[More info](https://stackoverflow.com/questions/34662574/node-js-getting-error-nodemon-internal-watch-failed-watch-enospc#34664097)
## Red Hat Enterprise Linux 8
1. Register system as root user to Red Hat Subscription Management (create a free Red Hat account if you don't have one yet).
```sh
subscription-manager register --username --password --auto-attach
dnf upgrade
reboot
```
1. Install NodeJS
```sh
sudo dnf module install nodejs:22
```
1. Install PNPM:
```sh
sudo npm install pnpm
```
1. Install FFmpeg
```sh
sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-$(arch)-rpms"
sudo dnf install --nogpgcheck https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install --nogpgcheck https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm
sudo dnf upgrade
sudo dnf install ffmpeg
```
1. Run:
```sh
sudo dnf module enable postgresql:16 # Default stream is PostgreSQL 10, too old for PeerTube
sudo dnf install nginx postgresql postgresql-server postgresql-contrib openssl gcc-c++ make wget redis git
psql --version # Should be >= 14
```
1. You'll need a symlink for python3 to python for youtube-dl to work
```sh
sudo alternatives --set python3 /usr/bin/python
```
1. Initialize the PostgreSQL database:
```sh
sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
```
Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis:
```sh
sudo systemctl enable --now redis
sudo systemctl enable --now postgresql
```
If you are running the production guide, you also need to slightly pre-configure nginx, because nginx is packaged differently in the Red Hat family distributions:
1. Configure nginx
```sh
sudo mkdir /etc/nginx/sites-available
sudo mkdir /etc/nginx/sites-enabled
sudo ln -s /etc/nginx/sites-enabled/peertube /etc/nginx/conf.d/peertube.conf
sudo systemctl enable --now nginx
```
1. Firewall
By default, you cannot access your server via public IP. To do so, you must configure firewall:
* Ports used by peertube dev setup:
```sh
sudo firewall-cmd --permanent --zone=public --add-port=3000/tcp
sudo firewall-cmd --permanent --zone=public --add-port=9000/tcp
```
* Optional
```sh
sudo firewall-cmd --permanent --zone=public --add-service=http
sudo firewall-cmd --permanent --zone=public --add-service=https
```
* Reload firewall
```sh
sudo firewall-cmd --reload
```
1. Configure max ports
This is necessary if you are running dev setup, otherwise you will have errors with `nodemon`
```sh
echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
```
[More info](https://stackoverflow.com/questions/34662574/node-js-getting-error-nodemon-internal-watch-failed-watch-enospc#34664097)
## FreeBSD
On a fresh install of [FreeBSD](https://www.freebsd.org), new system or new jail:
1. bootstrap pkg, initialize db and install peertube's dependencies, always as root (sudo not yet installed):
```sh
pkg
pkg update
pkg install -y sudo bash wget git python nginx pkgconf postgresql16-server postgresql16-contrib redis openssl node npm ffmpeg unzip
```
1. install `sharp` build dependencies: https://sharp.pixelplumbing.com/install/#building-from-source
1. Install PNPM:
```sh
sudo npm install pnpm
```
1. Allow users in the wheel group (hope you don't forgot to add your user on wheel group!) to use sudo.
```sh
visudo
```
Uncomment the line 90
```
%wheel ALL=(ALL) ALL
```
1. Enable nginx, redis, postgresql services and initialize database.
```sh
sysrc postgresql_enable="YES"
sysrc redis_enable="YES"
sysrc nginx_enable="YES"
```
Initialize database and start services
```sh
service postgresql initdb
service postgresql start
service redis start
service nginx start
```
## macOS
1. Add the packages:
```sh
brew install ffmpeg nginx postgresql@16 openssl gcc make redis git
brew install pnpm
```
1. Run the services:
```sh
brew services run postgresql@16
brew services run redis
```
On macOS, the `postgresql` user can be `_postgres` instead of `postgres`.
If `sudo -u postgres createuser -P peertube` gives you an `unknown user: postgres` error, you can try `sudo -u _postgres createuser -U peertube`.
## Gentoo
1. Add this to ``/etc/portage/sets/peertube``:
```
net-libs/nodejs
sys-apps/pnpm
media-video/ffmpeg[x264] # Optionally add vorbis,vpx
dev-db/postgresql:16 # Any slot >= 14 works
dev-db/redis
dev-vcs/git
app-arch/unzip
dev-lang/python
dev-lang/python-exec
www-servers/nginx
# Optional, client for Let’s Encrypt:
# app-crypt/certbot
```
1. If you are on a "stable" Gentoo you need to accept the testing keyword ~amd64 pnpm:
```sh
mkdir -p /etc/portage/package.keywords
cat << EOF >> /etc/portage/package.keywords/peertube
# required by pnpm (argument) for PeerTube
sys-apps/pnpm ~amd64
EOF
```
1. Compile the peertube set:
```sh
emerge -a @peertube
```
1. Initialize the PostgreSQL database if you just merged it:
```sh
emerge --config postgresql
```
1. (For OpenRC) Enable and then start the services (replace with the correct PostgreSQL slot):
```sh
rc-update add redis
rc-update add postgresql-16
rc-service redis start
rc-service postgresql-16 start
```
1. Create Python version symlink for youtube-dl:
```sh
emerge -1 python-exec
```
## OpenBSD
1. Install Packages:
```sh
pkg_add sudo bash wget git python nginx pkgconf postgresql-server postgresql-contrib redis openssl
```
1. Install PNPM:
```sh
sudo npm install pnpm
```
1. Allow users in the wheel group to use sudo
```sh
visudo
```
Uncomment line #43:
```
%wheel ALL=(ALL) ALL
```
1. Enable services:
```sh
rcctl enable postgresql redis nginx
```
## Other distributions
Feel free to update this file in a pull request!
---
### Support Doc Docker (`support/doc/docker.md`)
# Docker guide
This guide requires [docker](https://www.docker.com/community-edition) and
[docker-compose V2](https://docs.docker.com/compose/install/).
```shell
docker compose version # Must be > 2.x.x
```
## Install
**PeerTube does not support webserver host change**. Keep in mind your domain
name is definitive after your first PeerTube start.
#### Go to your workdir
:::info
The guide that follows assumes an empty workdir, but you can also clone the repository, use the master branch and `cd support/docker/production`.
:::
```shell
cd /your/peertube/directory
```
#### Get the latest Compose file
```shell
curl https://raw.githubusercontent.com/chocobozzz/PeerTube/master/support/docker/production/docker-compose.yml > docker-compose.yml
```
View the source of the file you're about to download: [docker-compose.yml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/docker-compose.yml)
#### Get the latest env_file
```shell
curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/docker/production/.env > .env
```
View the source of the file you're about to download: [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env)
#### Tweak the `docker-compose.yml` file there according to your needs
```shell
sudo nano docker-compose.yml
```
#### Then tweak the `.env` file to change the environment variables settings
```shell
sudo nano .env
```
In the downloaded example [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env), you must replace:
- ``
- ``
- `` without 'https://'
- ``
- ``
Other environment variables are used in
[/support/docker/production/config/custom-environment-variables.yaml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/custom-environment-variables.yaml) and can be
intuited from usage.
#### Webserver
::: info
The docker compose file includes a configured web server. You can skip this part and comment the appropriate section in the docker compose if you use another webserver/proxy.
:::
Install the template that the nginx container will use.
The container will generate the configuration by replacing `${WEBSERVER_HOST}` and `${PEERTUBE_HOST}` using your docker compose env file.
```shell
mkdir -p docker-volume/nginx docker-volume/nginx-logs
curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/nginx/peertube > docker-volume/nginx/peertube
```
You need to manually generate the first SSL/TLS certificate using Let's Encrypt:
```shell
mkdir -p docker-volume/certbot
docker run -it --rm --name certbot -p 80:80 -v "$(pwd)/docker-volume/certbot/conf:/etc/letsencrypt" certbot/certbot certonly --standalone
```
A dedicated container in the docker-compose will automatically renew this certificate and reload nginx.
#### Test your setup
_note_: Newer versions of compose are called with `docker compose` instead of `docker-compose`, so remove the dash in all steps that use this command if you are getting errors.
Run your containers:
```shell
docker compose up
```
#### Obtaining your automatically-generated admin credentials
You can change the automatically created password for user root by running this command from peertube's root directory:
```shell
docker compose exec -u peertube peertube npm run reset-password -- -u root
```
You can also grep your peertube container's logs for the default `root` password. You're going to want to run `docker-compose logs peertube | grep -A1 root` to search the log output for your new PeerTube's instance admin credentials which will look something like this.
```bash
docker compose logs peertube | grep -A1 root
peertube_1 | [example.com:443] 2019-11-16 04:26:06.082 info: Username: root
peertube_1 | [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
```
#### Obtaining Your Automatically Generated DKIM DNS TXT Record
[DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) signature sending and RSA keys generation are enabled by the default Postfix image `mwader/postfix-relay` with [OpenDKIM](http://www.opendkim.org/).
Run `cat ./docker-volume/opendkim/keys/*/*.txt` to display your DKIM DNS TXT Record containing the public key to configure to your domain :
```bash
cat ./docker-volume/opendkim/keys/*/*.txt
peertube._domainkey.mydomain.tld. IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dx7wLGPFVaxVQ4TGym/eF89aQ8oMxS9v5BCc26Hij91t2Ci8Fl12DHNVqZoIPGm+9tTIoDVDFEFrlPhMOZl8i4jU9pcFjjaIISaV2+qTa8uV1j3MyByogG8pu4o5Ill7zaySYFsYB++cHJ9pjbFSC42dddCYMfuVgrBsLNrvEi3dLDMjJF5l92Uu8YeswFe26PuHX3Avr261n"
"j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" ) ; ----- DKIM key peertube for mydomain.tld
```
#### Administrator password
See the production guide ["Administrator" section](https://docs.joinpeertube.org/install/any-os#administrator)
#### What now?
See the production guide ["What now" section](https://docs.joinpeertube.org/install/any-os#what-now).
## Upgrade
::: warning
Check the changelog (in particular the *IMPORTANT NOTES* section): https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
:::
Pull the latest images:
```shell
cd /your/peertube/directory
docker compose pull
```
Stop, delete the containers and internal volumes (to invalidate static client files shared by `peertube` and `webserver` containers):
```shell
docker compose down -v
```
Update the nginx configuration:
```shell
mv docker-volume/nginx/peertube docker-volume/nginx/peertube.bak
curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/nginx/peertube > docker-volume/nginx/peertube
```
Rerun PeerTube:
```shell
docker compose up -d
```
## Upgrade PostgreSQL container
If you want to upgrade your PostgreSQL container version (for example because your current version is about to no longer be supported),
you need to plan downtime (to export current cluster and re-import data in new one).
When you're ready, go inside your PeerTube docker compose directory:
```sh
cd /docker-compose/directory
```
Prepare the backups directory and stop all containers except the database:
```sh
mkdir -p backups
docker compose stop peertube webserver certbot
```
Go inside the database container:
```sh
docker compose exec -it postgres /bin/bash
```
And export the database (you don't need to replace `$POSTGRES_*` variables, they are automatically set by your env file from docker compose):
```sh
export PGUSER="$POSTGRES_USER"
export PGDATABASE="$POSTGRES_DB"
export PGPASSWORD="$POSTGRES_PASSWORD"
pg_dumpall > "/tmp/pg.dump"
```
Exit the container:
```sh
exit
```
Copy the dump from the container:
```sh
docker compose cp postgres:/tmp/pg.dump backups/pg.dump
```
Stop the database container and prepare the data for the new cluster:
```sh
docker compose stop postgres
mv ./docker-volume/db ./docker-volume/db.bak
mkdir ./docker-volume/db && chmod 700 ./docker-volume/db
```
Upgrade your PostgreSQL container version (for example replace `postgres:13-alpine` by `postgres:17-alpine`):
```sh
vim docker-compose.yml
```
Pull new PostgreSQL Docker image:
```sh
docker compose pull
```
Restart PostgreSQL only container and wait until you see: `database system is ready to accept connections`
```sh
docker compose up -d postgres
docker compose logs -f postgres
```
Copy the database dump inside the container:
```sh
docker compose cp "backups/pg.dump" postgres:/tmp/pg.dump
```
Go inside the container
```sh
docker compose exec -it postgres /bin/bash
```
Check the PostgreSQL version and re-import database data.
Then, reset the PeerTube database user password to fix a potential authentication issue if the old password hash algorithm has been deprecated.
```sh
export PGUSER="$POSTGRES_USER"
export PGDATABASE="$POSTGRES_DB"
export PGPASSWORD="$POSTGRES_PASSWORD"
psql -U "$POSTGRES_USER" -c "SELECT version();"
psql -U "$POSTGRES_USER" -f /tmp/pg.dump
psql -U "$POSTGRES_USER" -c "ALTER USER $POSTGRES_USER WITH PASSWORD '$POSTGRES_PASSWORD';"
```
Exit the container:
```sh
exit
```
Restart other services and check everything is fine:
```sh
docker compose up -d peertube webserver certbot
docker compose logs -f peertube
```
If you're happy with the results, you can remove backups directory and old data directories:
```sh
rm -rf ./docker-volume/db.bak backups
```
## Build
### Production
```shell
git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
cd /tmp/peertube
docker build . -f ./support/docker/production/Dockerfile
```
### Development
We don't have a Docker image for development. See [the CONTRIBUTING guide](https://docs.joinpeertube.org/contribute/getting-started#develop) for more information on how you can hack PeerTube!
---
### Support Doc Production (`support/doc/production.md`)
# Production guide
* [Installation](#installation)
* [Upgrade](#upgrade)
## Installation
Please don't install PeerTube for production on a device behind a low bandwidth connection (example: your ADSL link).
If you want information about the appropriate hardware to run PeerTube, please see the [FAQ](https://joinpeertube.org/en_US/faq#should-i-have-a-big-server-to-run-peertube).
### :hammer: Dependencies
Follow the steps of the [dependencies guide](/support/doc/dependencies.md).
### :construction_worker: PeerTube user
Create a `peertube` user with `/var/www/peertube` home:
::: code-group
```bash [GNU/Linux]
sudo useradd -m -d /var/www/peertube -s /usr/sbin/nologin peertube
```
```bash [FreeBSD]
sudo pw useradd -n peertube -d /var/www/peertube -s /usr/sbin/nologin -m
```
:::
Ensure the peertube root directory is traversable by nginx:
```bash
sudo chmod 755 /var/www/peertube
```
### :card_file_box: Database
Create the production database and a peertube user inside PostgreSQL:
```bash
cd /var/www/peertube
sudo -u postgres createuser -P peertube
```
Here you should enter a password for PostgreSQL `peertube` user, that should be copied in `production.yaml` file.
Don't just hit enter else it will be empty.
```bash
sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
```
Then enable extensions PeerTube needs:
```bash
sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod
```
### :page_facing_up: Prepare PeerTube directory
Fetch the latest tagged version of Peertube:
```bash
VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
```
Open the peertube directory, create a few required directories:
```bash
cd /var/www/peertube
sudo -u peertube mkdir config storage versions
sudo -u peertube chmod 750 config/
```
Download the latest version of the Peertube client, unzip it and remove the zip:
```bash
cd /var/www/peertube/versions
# Releases are also available on https://builds.joinpeertube.org/release
sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip"
sudo -u peertube unzip -q peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip
```
Install Peertube:
::: code-group
```bash [GNU/Linux]
cd /var/www/peertube
sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
cd ./peertube-latest && sudo -H -u peertube npm run install-node-dependencies -- --production
```
```bash [FreeBSD]
cd /var/www/peertube
sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
cd ./peertube-latest && sudo -H -u peertube npm run install-node-dependencies -- --production
sudo -u peertube pnpm add --workspace-root --no-lockfile --prod node-addon-api node-gyp
sudo -u peertube SHARP_FORCE_GLOBAL_LIBVIPS=1 npm explore sharp -- npm run build
```
:::
### :wrench: PeerTube configuration
Copy the default configuration file that contains the default configuration provided by PeerTube.
You **must not** update this file.
```bash
cd /var/www/peertube
sudo -u peertube cp peertube-latest/config/default.yaml config/default.yaml
```
Now copy the production example configuration:
```bash
cd /var/www/peertube
sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
```
Then edit the `config/production.yaml` file according to your webserver and database configuration. In particular:
* `webserver`: Reverse proxy public information
* `secrets`: Secret strings you must generate manually (PeerTube version >= 5.0)
* `database`: PostgreSQL settings
* `redis`: Redis settings
* `smtp`: If you want to use emails
* `admin.email`: To correctly fill `root` user email
Keys defined in `config/production.yaml` will override keys defined in `config/default.yaml`.
**PeerTube does not support webserver host change**. Even though [PeerTube CLI can help you to switch hostname](https://docs.joinpeertube.org/maintain/tools#update-host-js) there's no official support for that since it is a risky operation that might result in unforeseen errors.
### :truck: Webserver
We only provide official configuration files for Nginx.
Copy the nginx configuration template:
```bash
sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
```
Set the domain for the webserver configuration file by replacing `[peertube-domain]` with the domain for the peertube server:
```bash
sudo sed -i 's/${WEBSERVER_HOST}/[peertube-domain]/g' /etc/nginx/sites-available/peertube
sudo sed -i 's/${PEERTUBE_HOST}/127.0.0.1:9000/g' /etc/nginx/sites-available/peertube
```
Then modify the webserver configuration file. Please pay attention to:
* the `alias` and `root` directives paths, the paths must correspond to your PeerTube filesystem location
* the `proxy_limit_rate` and `limit_rate` directives if you plan to stream high bitrate videos (like 4K at 60FPS)
```bash
sudo vim /etc/nginx/sites-available/peertube
```
Activate the configuration file:
```bash
sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
```
To generate the certificate for your domain as required to make https work you can use [Let's Encrypt](https://letsencrypt.org/):
```bash
sudo systemctl stop nginx
sudo certbot certonly --standalone --post-hook "systemctl restart nginx"
sudo systemctl restart nginx
```
Certbot should have installed a cron to automatically renew your certificate.
Since our nginx template supports webroot renewal, we suggest you to update the renewal config file to use the `webroot` authenticator:
```bash
# Replace authenticator = standalone by authenticator = webroot
# Add webroot_path = /var/www/certbot
sudo vim /etc/letsencrypt/renewal/your-domain.com.conf
```
If you plan to have many concurrent viewers on your PeerTube instance, consider increasing `worker_connections` value: https://nginx.org/en/docs/ngx_core_module.html#worker_connections.
If using FreeBSD
On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)
```bash
sudo pkg install dehydrated
```
### :alembic: Linux TCP/IP Tuning
```bash
sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
```
Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
links as we often encounter in a video server.
### :bricks: systemd
If your OS uses systemd, copy the configuration template:
```bash
sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
```
Check the service file (PeerTube paths and security directives):
```bash
sudo vim /etc/systemd/system/peertube.service
```
Tell systemd to reload its config:
```bash
sudo systemctl daemon-reload
```
If you want to start PeerTube on boot:
```bash
sudo systemctl enable peertube
```
Run:
```bash
sudo systemctl start peertube
sudo journalctl -feu peertube
```
If using FreeBSD
On FreeBSD, copy the startup script and update rc.conf:
```bash
sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
sudo sysrc peertube_enable="YES"
```
Run:
```bash
sudo service peertube start
```
If using OpenRC
If your OS uses OpenRC, copy the service script:
```bash
sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
sudo cp /var/www/peertube/peertube-latest/support/conf.d/peertube /etc/conf.d/
```
If you want to start PeerTube on boot:
```bash
sudo rc-update add peertube default
```
Run and print last logs:
```bash
sudo /etc/init.d/peertube start
tail -f /var/log/peertube/peertube.log
```
### :technologist: Administrator
The administrator username is `root` and the password is automatically generated. It can be found in PeerTube
logs (path defined in `production.yaml`). You can also set another password with:
```bash
cd /var/www/peertube/peertube-latest && sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
```
Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
to your own administrator password, although it must be 6 characters or more.
### :tada: What now?
Now your instance is up you can:
* Add your instance to the public PeerTube instances index if you want to: https://instances.joinpeertube.org/
* Check [available CLI tools](/support/doc/tools.md)
## Upgrade
### PeerTube instance
**Check the changelog (in particular the *IMPORTANT NOTES* section):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
Run the upgrade script (the password it asks is PeerTube's database user password):
::: code-group
```bash [GNU/Linux]
cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
```
```bash [FreeBSD]
cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
sudo -u peertube pnpm add --workspace-root --no-lockfile --prod node-addon-api node-gyp
sudo -u peertube SHARP_FORCE_GLOBAL_LIBVIPS=1 npm explore sharp -- npm run build
```
:::
If you have `git` installed on your system, the upgrade will create a `production.yaml.new` file with differences marked as merge conflicts.
Review this file and replace your existing `production.yaml` with it before restarting.
```bash
# Make sure you first updated your configuration per the note above
sudo systemctl restart peertube # Or use your OS command to restart PeerTube if you don't use systemd
```
You may want to run `sudo -u peertube pnpm store prune` after several upgrades to free up disk space.
Prefer manual upgrade?
Make a SQL backup
```bash
SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
```
Fetch the latest tagged version of Peertube:
```bash
VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
```
Download the new version and unzip it:
```bash
cd /var/www/peertube/versions && \
sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
sudo -u peertube unzip -o peertube-${VERSION}.zip && \
sudo -u peertube rm peertube-${VERSION}.zip
```
Install node dependencies:
```bash
cd /var/www/peertube/versions/peertube-${VERSION} && \
sudo -H -u peertube npm run install-node-dependencies -- --production
```
Copy new configuration defaults values and update your configuration file:
```bash
sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
diff -u /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
```
Change the link to point to the latest version:
```bash
cd /var/www/peertube && \
sudo unlink ./peertube-latest && \
sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
```
### Update PeerTube configuration
If your system has `git` installed, the auto upgrade script should have created a `config/production.yaml.new` file that merges your current configuration file with the new configuration keys introduced by the new PeerTube version.
Review the file, check and fix any potential conflicts:
```bash
cd /var/www/peertube && sudo -u peertube diff config/production.yaml config/production.yaml.new
```
Then replace your current configuration file by the new one:
```bash
cd /var/www/peertube && sudo -u peertube cp config/production.yaml.new config/production.yaml
```
### Update nginx configuration
Check changes in nginx configuration:
```bash
cd /var/www/peertube/versions
diff -u "$(ls -t | head -2 | tail -1)/support/nginx/peertube" "$(ls -t | head -1)/support/nginx/peertube"
```
### Update systemd service
Check changes in systemd configuration:
```bash
cd /var/www/peertube/versions
diff -u "$(ls -t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls -t | head -1)/support/systemd/peertube.service"
```
If using OpenRC
```bash
cd /var/www/peertube/versions
diff -u "$(ls -t | head -2 | tail -1)/support/init.d/peertube" "$(ls -t | head -1)/support/init.d/peertube"
diff -u "$(ls -t | head -2 | tail -1)/support/conf.d/peertube" "$(ls -t | head -1)/support/conf.d/peertube"
```
### Restart PeerTube
If you changed your nginx configuration:
```bash
sudo systemctl reload nginx
```
If you changed your systemd configuration:
```bash
sudo systemctl daemon-reload
```
Restart PeerTube and check the logs:
```bash
sudo systemctl restart peertube && sudo journalctl -fu peertube
```
### Things went wrong?
Change `peertube-latest` destination to the previous version and restore your SQL backup:
```bash
OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-20180119-1018.bak" && \
cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
sudo -u postgres pg_restore -c -C -d peertube_prod "$SQL_BACKUP_PATH" && \
sudo systemctl restart peertube
```
---
### Support Doc Tools (`support/doc/tools.md`)
# CLI tools guide
[[toc]]
## Remote PeerTube CLI
`peertube-cli` is a tool that communicates with a PeerTube instance using its [REST API](https://docs.joinpeertube.org/api-rest-reference.html).
It can be launched from a remote server/computer to easily upload videos, manage plugins, redundancies etc.
### Installation
Ensure you have `node` installed on your system:
```bash
node --version # Should be >= 22.x
```
Then install the CLI:
```bash
sudo npm install @peertube/peertube-cli
```
### CLI wrapper
The wrapper provides a convenient interface to the following sub-commands.
```
Usage: peertube-cli [command] [options]
Options:
-v, --version output the version number
-h, --help display help for command
Commands:
auth Register your accounts on remote instances to use them with other commands
upload|up [options] Upload a video on a PeerTube instance
redundancy|r Manage instance redundancies
plugins|p Manage instance plugins/themes
get-access-token|token [options] Get a peertube access token
help [command] display help for command
```
The wrapper can keep track of instances you have an account on. We limit to one account per instance for now.
```bash
peertube-cli auth add -u 'PEERTUBE_URL' -U 'PEERTUBE_USER' --password 'PEERTUBE_PASSWORD'
```
Now list the account(s) you've created
```bash
peertube-cli auth list
```
```
┌──────────────────────────────┬──────────────────────────────┐
│ instance │ login │
├──────────────────────────────┼──────────────────────────────┤
│ 'PEERTUBE_URL' │ 'PEERTUBE_USER' │
└──────────────────────────────┴──────────────────────────────┘
```
You can now use that account to execute sub-commands without feeding the `--url`, `--username` and `--password` parameters:
```bash
peertube-cli upload
```
```bash
peertube-cli plugins list
...
```
#### peertube-cli upload
You can use this script to upload videos directly from the CLI.
Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
```bash
cd ${CLONE}
peertube-cli upload --help
```
#### peertube-cli plugins
Install/update/uninstall or list local or NPM PeerTube plugins:
```bash
cd ${CLONE}
peertube-cli plugins --help
peertube-cli plugins list --help
peertube-cli plugins install --help
peertube-cli plugins update --help
peertube-cli plugins uninstall --help
peertube-cli plugins install --path /my/plugin/path
peertube-cli plugins install --npm-name peertube-theme-example
```
#### peertube-cli redundancy
Manage (list/add/remove) video redundancies:
To list your videos that are duplicated by remote instances:
```bash
peertube-cli redundancy list-remote-redundancies
```
To list remote videos that your instance duplicated:
```bash
peertube-cli redundancy list-my-redundancies
```
To duplicate a specific video in your redundancy system:
```bash
peertube-cli redundancy add --video 823
```
To remove a video redundancy:
```bash
peertube-cli redundancy remove --video 823
```
## PeerTube runner
PeerTube supports VOD/Live transcoding and VOD transcription (PeerTube >= 6.2) by a remote PeerTube runner.
The runner communicates with the PeerTube instance using HTTP and WebSocket and doesn't need to have a public IP.
So you can run a runner on a classic server, a non-public server or even on your own computer!
You can read the admin documentation on how to use PeerTube runners on https://docs.joinpeertube.org/admin/remote-runners
### Runner installation
Ensure you have `node`, `ffmpeg` and `ffprobe` installed on your system:
```bash
node --version # Should be >= 22.x
ffprobe -version # Should be >= 4.3
ffmpeg -version # Should be >= 4.3
```
If you want to use video transcription:
```bash
pip install whisper-ctranslate2 # or pipx install whisper-ctranslate2 depending on your distribution
```
Then install the CLI:
```bash
sudo npm install @peertube/peertube-runner
```
### Configuration
The runner uses env paths like `~/.config`, `~/.cache` and `~/.local/share` directories to store runner configuration or temporary files.
Multiple PeerTube runners can run on the same OS by using the `--id` CLI option (each runner uses its own config/tmp directories):
```bash
peertube-runner [commands] --id instance-1
peertube-runner [commands] --id instance-2
peertube-runner [commands] --id instance-3
```
You can change the runner configuration (jobs concurrency, ffmpeg threads/nice, whisper engines/models, etc.) by editing `~/.config/peertube-runner-nodejs/[id]/config.toml`.
The runner TOML config template consists of:
```toml
[jobs]
# How much concurrent jobs the runner can execute in parallel
concurrency = 2
[ffmpeg]
# How much threads a ffmpeg process can use
# 0 -> let ffmpeg automatically choose
threads = 0
nice = 20
[transcription]
# Choose between "openai-whisper" or "whisper-ctranslate2"
# Engine binary has to be installed manually (unlike the PeerTube instance that can install whisper automatically)
engine = "whisper-ctranslate2"
# Optional whisper binary path if not available in global path
enginePath = "/var/prunner/.local/pipx/venvs/whisper-ctranslate2/bin/whisper-ctranslate2"
# Whisper model: "tiny", "base", "small", "medium", "large-v2" or "large-v3"
model = "large-v2"
# Registered instances are saved in the config file
[[registeredInstances]]
url = "..." # URL of the instance
runnerToken = "..." # Shared runner token secret
runnerName = "..." # Runner name declared to the PeerTube instance
[[registeredInstances]]
url = "..."
runnerToken = "..."
runnerName = "..."
```
### Run the server
#### In a shell
You need to run the runner in server mode first so it can run transcoding jobs of registered PeerTube instances:
```bash
peertube-runner server
```
You can also decide which kind of job the runner can execute with `--enable-job ` option.
This way you can have one dedicated runner for transcription tasks (on a GPU machine for example) and another one for transcoding tasks.
Only transcription tasks
```bash
peertube-runner server --enable-job video-transcription
```
Only VOD transcoding tasks
```bash
peertube-runner server --enable-job vod-web-video-transcoding --enable-job vod-hls-transcoding --enable-job vod-audio-merge-transcoding
```
Only "studio" transcoding
```bash
peertube-runner server --enable-job video-studio-transcoding
```
Only "live" transcoding
```bash
peertube-runner server --enable-job live-rtmp-hls-transcoding
```
#### As a Systemd service
If your OS uses systemd, you can also configure a service so that the runner starts automatically.
To do so, first create a dedicated user. Here, we are calling it `prunner`, but you can choose whatever name you want.
We are using `/srv/prunner` as his home dir, but you can choose any other path.
```bash
useradd -m -d /srv/prunner -s /usr/sbin/nologin prunner
```
::: info Note
If you want to use `/home/prunner`, you have to set `ProtectHome=false` in the systemd configuration (see below).
:::
Now, you can create the `/etc/systemd/system/prunner.service` file (don't forget to adapt path and user/group names if you changed it):
```Systemd
[Unit]
Description=PeerTube runner daemon
After=network.target
[Service]
Type=simple
Environment=NODE_ENV=production
User=prunner
Group=prunner
ExecStart=peertube-runner server
WorkingDirectory=/srv/prunner
SyslogIdentifier=prunner
Restart=always
; Some security directives.
; Mount /usr, /boot, and /etc as read-only for processes invoked by this service.
ProtectSystem=full
; Sets up a new /dev mount for the process and only adds API pseudo devices
; like /dev/null, /dev/zero or /dev/random but not physical devices. Disabled
; by default because it may not work on devices like the Raspberry Pi.
PrivateDevices=false
; Ensures that the service process and all its children can never gain new
; privileges through execve().
NoNewPrivileges=true
; This makes /home, /root, and /run/user inaccessible and empty for processes invoked
; by this unit. Make sure that you do not depend on data inside these folders.
ProtectHome=true
; Drops the sys admin capability from the daemon.
CapabilityBoundingSet=~CAP_SYS_ADMIN
[Install]
WantedBy=multi-user.target
```
:::info Note
You can add the parameter `--id instance-1` on the `ExecStart` line, if you want to have multiple instances.
You can then create multiple separate services. They can use the same user and path.
:::
Finally, to enable the service for the first time:
```bash
systemctl daemon-reload
systemctl enable prunner.service
systemctl restart prunner.service
```
Next time, if you need to start/stop/restart the service:
```bash
systemctl stop prunner.service
systemctl start prunner.service
systemctl restart prunner.service
```
You can also check the status (and last logs):
```bash
systemctl status prunner.service
```
To edit the runner configuration: juste edit the `/srv/prunner/.config/peertube-runner-nodejs/default/config.toml` file,
and restart the service (this file will be created when the runner starts for the first time).
If you are using the `--id` parameter, you can change specific configuration by editing the file `/srv/prunner/.config/peertube-runner-nodejs/[id]/config.toml`.
::: info
For every peertube-runner commands described below, you have to run them as the `prunner` user.
So for example, to call the `list-registered` command: `sudo -u prunner peertube-runner list-registered`.
Otherwise the script will read the wrong configuration and cache files, and won't work as expected.
:::
### Register
Then, you can register the runner to process transcoding job of a remote PeerTube instance:
::: code-group
```bash [Shell]
peertube-runner register --url http://peertube.example.com --registration-token ptrrt-... --runner-name my-runner-name
```
```bash [Systemd]
sudo -u prunner peertube-runner register --url http://peertube.example.com --registration-token ptrrt-... --runner-name my-runner-name
```
:::
The runner will then use a websocket connection with the PeerTube instance to be notified about new available transcoding jobs.
### Unregister
To unregister a PeerTube instance:
::: code-group
```bash [Shell]
peertube-runner unregister --url http://peertube.example.com --runner-name my-runner-name
```
```bash [Systemd]
sudo -u prunner peertube-runner unregister --url http://peertube.example.com --runner-name my-runner-name
```
:::
### List registered instances
::: code-group
```bash [Shell]
peertube-runner list-registered
```
```bash [Systemd]
sudo -u prunner peertube-runner list-registered
```
:::
### List jobs
**Runner >= 0.1.0**
To list jobs that are processed by the runner:
::: code-group
```bash [Shell]
peertube-runner list-jobs
peertube-runner list-jobs --include-payload
```
```bash [Systemd]
sudo -u prunner peertube-runner list-jobs
sudo -u prunner peertube-runner list-jobs --include-payload
```
:::
### Graceful shutdown
Ask the runner to shutdown when it has finished all of its current tasks:
::: code-group
```bash [Shell]
peertube-runner graceful-shutdown
```
```bash [Systemd]
sudo -u prunner peertube-runner graceful-shutdown
```
:::
### Update the runner package
You can check if there is a new runner version using:
```bash
sudo npm outdated -g @peertube/peertube-runner
```
```
Package Current Wanted Latest Location Depended by
@peertube/peertube-runner 0.0.6 0.0.7 0.0.7 node_modules/@peertube/peertube-runner lib
```
To update the runner:
Update the package
```bash
sudo npm update -g @peertube/peertube-runner
```
Check that the version changed (optional)
```bash
sudo npm list -g @peertube/peertube-runner
```
Restart the service (if you are using systemd)
```bash
sudo systemctl restart prunner.service
```
## Server tools
Server tools are scripts that interact directly with the code of your PeerTube instance.
They must be run on the server, in `peertube-latest` directory.
### Parse logs
To parse PeerTube last log file:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run parse-log -- --level info
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run parse-log -- --level info
```
:::
`--level` is optional and could be `info`/`warn`/`error`
You can also remove SQL or HTTP logs using `--not-tags`:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run parse-log -- --level debug --not-tags http sql
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run parse-log -- --level debug --not-tags http sql
```
:::
### Regenerate video and playlist thumbnails
Regenerating local video and playlist thumbnails could be useful because new PeerTube releases may increase thumbnail sizes:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run regenerate-thumbnails
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run regenerate-thumbnails
```
:::
### Add or replace specific video file
You 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.
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.
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
```
:::
### Move video files from filesystem to object storage
Use this script to move video related files (video files, original video file, captions, etc.) to object storage.
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
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]
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-object-storage -v [videoUUID]
```
:::
The script can also move all video related files that are not already in object storage:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
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
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-object-storage --all-videos
```
:::
### Move video files from object storage to filesystem
**PeerTube >= 6.0**
Use this script to move video related files (video files, original video file, captions, etc.) from object storage to the PeerTube instance filesystem.
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-move-video-storage-job -- --to-file-system -v [videoUUID]
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-file-system -v [videoUUID]
```
:::
The script can also move all video related files that are not already on the filesystem:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-move-video-storage-job -- --to-file-system --all-videos
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-move-video-storage-job -- --to-file-system --all-videos
```
:::
### Cleanup remote files
**PeerTube >= 6.2**
Use this script to recover disk space by removing remote files (thumbnails, avatars...) that can be re-fetched later by your PeerTube instance on-demand.
Restart PeerTube after running this script.
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run house-keeping -- --delete-remote-files
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run house-keeping -- --delete-remote-files
```
:::
### Generate storyboard
**PeerTube >= 6.0**
Use this script to generate storyboard of a specific video:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-generate-storyboard-job -- -v [videoUUID]
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-generate-storyboard-job -- -v [videoUUID]
```
:::
The script can also generate all missing storyboards of local videos:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-generate-storyboard-job -- --all-videos
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run create-generate-storyboard-job -- --all-videos
```
:::
### Prune filesystem/object storage
Some transcoded videos or shutdown at a bad time can leave some unused files on your storage.
To delete these files (a confirmation will be demanded first):
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run prune-storage
```
:::
It's also possible to remove more local files if your stop PeerTube using the `--offline` option:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage -- --offline
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run prune-storage -- --offline
```
:::
### Update PeerTube instance domain name
**Changing the hostname is unsupported and may be a risky operation, especially if you have already federated.**
If you started PeerTube with a domain, and then changed it you will have
invalid torrent files and invalid URLs in your database. To fix this, you have
to run the command below (keep in mind your follower instances will NOT update their URLs).
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run update-host
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run update-host
```
:::
### Reset user password
To reset a user password from CLI, run:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u target_username
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run reset-password -- -u target_username
```
:::
### Install or uninstall plugins
The difference with `peertube plugins` CLI is that these scripts can be used even if PeerTube is not running.
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).
To install/update a plugin or a theme from the disk:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:install -- --plugin-path /local/plugin/path
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run plugin:install -- --plugin-path /local/plugin/path
```
:::
From NPM:
::: code-group
```bash
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:install -- --npm-name peertube-plugin-myplugin
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run plugin:install -- --npm-name peertube-plugin-myplugin
```
:::
To uninstall a plugin or a theme:
::: code-group
```bash [Classic installation]
cd /var/www/peertube/peertube-latest; \
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin
```
```bash [Docker]
cd /var/www/peertube-docker; \
docker compose exec -u peertube peertube npm run plugin:uninstall -- --npm-name peertube-plugin-myplugin
```
:::
---
### Support Doc Translation (`support/doc/translation.md`)
# Translation
We use [Weblate](https://weblate.org) as translation platform.
Please do not edit translation files directly from Git, you have to use Weblate!
If you don't see your locale in the platform you can add it directly in the Weblate interface.
Then, if you think there are enough translated strings, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues) so we add the new locale in PeerTube!
Translations are manually pulled and merged in PeerTube software and are publicly available in the next official release.
You can get a chance to see translations before the official release by going to https://peertube2.cpy.re which is updated every night with the latest PeerTube changes.
## How to
* Create an account: https://weblate.framasoft.org/accounts/register/
* Validate your email and follow the link sent
* Create your password (keep the `Current password` field empty) and set up your account
* To translate the PeerTube web, visit the PeerTube project page: https://weblate.framasoft.org/projects/peertube/
* To translate the PeerTube mobile application, visit the PeerTube App project page: https://weblate.framasoft.org/projects/peertube-app/
* Choose the file and the locale you want to translate
## Files
There are 4 files:
* **angular**: contains client strings
* **player**: contains player strings.
Most of the strings come from VideoJS, so you can help yourself by using [video.js JSON files](https://github.com/videojs/video.js/tree/master/lang)
* **server**: contains server strings clients can fetch in JSON format so they don't have to translate common PeerTube strings themselves (iso639 languages, privacies, licences...)
* **server-internal**: contains internal server strings used in the REST API responses or emails
## Tips
### Special tags
You must not translate special tags like ``.
For example:
```
- views
```
should be in French
```
- vues
```
### Singular/plural
For singular/plural translations, you must translate values inside `{` and `}`. **Please don't translate the word *other***
For example:
```
{VAR_PLURAL, plural, =0 {No videos} =1 {1 video} other { videos} }
```
should be in French
```
{VAR_PLURAL, plural, =0 {Aucune vidéo} =1 {1 vidéo} other { vidéos} }
```
---
### Support Doc Api Embeds (`support/doc/api/embeds.md`)
# PeerTube Embed API
PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
## Playground
Any PeerTube embed URL (ie `https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a`) can be viewed as an embedding playground which
allows you to test various aspects of PeerTube embeds. Simply replace `/embed` with `/test-embed` and visit the URL in a browser.
For instance, the playground URL for the above embed URL is `https://my-instance.example.com/videos/test-embed/52a10666-3a18-4e73-93da-e8d3c12c305a`.
## Quick Start
Given an existing PeerTube embed ` 
