PeerTube is a video hosting platform, similar to YouTube. It allows you to upload and view videos in multiple resolutions, transcode between resolutions (from 240p all the way up to 2160p), comment, and add thumbnails, tags, and subtitles to videos. It also supports livestreaming via RTMP. Unlike YouTube, it also allows you to upload videos from a URL or torrent, and it does not arbitrarily block or restrict your videos on upload.
NOTE: the following install instructions draw from the official PeerTube documentation, particularly the Production guide. We've made every effort to make sure our guides are accurate, but if the 10friends guide ever contradicts the official docs, you should defer to the latter. If you find any such contradictions, please contact us so we can fix them.
¶ DOCKER GUIDE
Those interested in installing PeerTube via Docker instead can find instructions in the official documentation here:
https://docs.joinpeertube.org/#/install-docker
¶ REQUIREMENTS
Due to the needs of storing, transcoding, and streaming video data, PeerTube has heavier requirements than other, more lightweight services (such as Pleroma). That said, this doesn't mean that you'll need a massively powerful server to run it. According to PeerTube's own FAQ, the minimum requirements are:
- CPU: 1 core with transcoding disabled, at least 2 if enabled (will function with 1, but much more slowly)
- RAM: 1GB
- Storage: Varies based on the number and size of video files uploaded, and the number of resolutions supported
You can choose to disable transcoding, or limit the supported resolutions on your instance if storage space is an issue. If you do support transcoding with all resolutions (240p to 2160p), then expect a given video file to take up anywhere from two to three times as much space (or more) on disk once fully processed after upload. It's advisable to monitor your server's storage periodically to make sure you don't exceed your capacity.
PeerTube supports multiple Operating Systems. For the sake of simplicity, our guide will assume you're using Debian/Ubuntu, but if you're using a different OS feel free to start from the dependencies guide on the project's official repository before moving on to their Production guide.
For each of the steps in this guide, you'll need to copy the commands shown into the prompt on your server and run them. It's okay if you don't understand what they all do, most of them will just automatically do the work needed to get PeerTube installed and set up. Some commands may ask you for more input. Simply follow the instructions that appear and the installation will complete successfully. If you have any problems during installation, you can ask for help in the official PeerTube channels here, or contact us here.
¶ INSTALLING REQUIRED PACKAGES
To install PeerTube, we'll first need to install some other programs. These include:
- curl (to download PeerTube releases)
- unzip (to unpack it)
- sudo (to grant root permissions needed for install)
- nano (to edit configuration files)
- certbot (to set up Let's Encrypt certificates for security)
- NodeJS 14.x (a programming environment)
- yarn (a package manager)
- nginx (a web server)
- ffmpeg (for video encoding and transcoding)
- g++ (a compiler)
- PostgreSQL and redis (database software)
First, install some of the basic utilities as the root user by running the following in the command prompt:
apt-get install curl sudo unzip nano
Since running commands as root can be risky, both in terms of security and otherwise, we'll create a new user to run the rest of the commands in this tutorial. In the example below, our new user is named "john". Feel free to change the name to whatever you like:
adduser john
Enter and then verify a password of your choice for the new user. You'll be prompted for details on the user account, but you can just press ENTER to skip through these. Enter Y at the end to confirm.
In order to run the commands needed for installation, our new user will require root permissions. Enter the following command to grant them:
usermod -aG sudo john
Now we'll switch to the new user account for the rest of the tutorial:
su - john
During installation, you may be asked for a password. Use the password for your new user account if prompted.
Install NodeJS 14.x:
curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs
Install yarn:
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
Check your yarn version:
yarn --version
It should match the latest release version found here. If the version you installed isn't the latest version, check here for instructions on how to fix that. Make sure you choose the appropriate Operating System from the drop menu.
Install python. PeerTube's python needs vary by OS version, so if you're running Debian 10 (Buster) or Ubuntu 18.04 (bionic) or lower, use the following:
sudo apt update
sudo apt install python-dev
python --version # Should be >= 2.x or >= 3.x
...but if you're using Debian 11 (Bullseye) or Ubuntu 20.04 (focal) or higher, use this instead:
sudo apt update
sudo apt install python3-dev python-is-python3 # python-is-python2 should also work
python --version # Should be >= 2.x or >= 3.x
Now we can update, and then install the rest of the packages we need:
sudo apt update
sudo apt install certbot nginx ffmpeg postgresql postgresql-contrib openssl g++ make redis-server git cron wget
And verify that ffmpeg and g++ are the correct versions:
ffmpeg -version (Should be >= 4.1)
g++ -v (Should be >= 5.x)
Finally, start redis and PostgreSQL before we move to installation proper:
sudo systemctl start redis postgresql
¶ CREATING PEERTUBE USER
First we'll create a peertube user with /var/www/peertube as its home directory, and give it a password:
sudo useradd -m -d /var/www/peertube -s /bin/bash -p peertube peertube
sudo passwd peertube
Make sure to remember the peertube user's password, as you may need it again in the future.
¶ DATABASE SETUP
Now create a different peertube user inside PostgreSQL, and a production database:
Warning: Make sure you create a password for your PostgreSQL peertube user and remember, because we'll need it later.
If you just hit enter without entering a password, it'll be left blank which could cause you trouble down the road.
sudo -u postgres createuser -P peertube
sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
...and set up some extensions that PeerTube needs:
sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod
¶ INSTALLING PEERTUBE
Fetch the latest version of PeerTube:
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 and make some other necessary directories inside it:
cd /var/www/peertube
sudo -u peertube mkdir config storage versions
sudo -u peertube chmod 750 config/
Go to the versions directory, download the latest version of PeerTube, unzip it, and remove the zip file:
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 peertube-${VERSION}.zip
sudo -u peertube rm peertube-${VERSION}.zip
Install PeerTube:
cd ../ && sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
cd ./peertube-latest && sudo -H -u peertube yarn install --production --pure-lockfile
¶ EDITING CONFIGURATION
Make a copy of the example configuration file:
cd /var/www/peertube && sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
The example configuration file (located at /var/www/peertube/peertube-latest/config/production.yaml.example) is a template that you can refer to for what your configuration is supposed to look like. As it's only a template, it uses placeholder values for things like the server domain name, admin e-mail, etc. The version we've just created (located at /var/www/peertube/config/production.yaml) will be the actual configuration file that PeerTube will use to run. As such, we need to edit it with the actual information about our server.
Open the configuration file for editing:
sudo nano config/production.yaml
Find the following section inside the file:
# Correspond to your reverse proxy server_name/listen configuration
webserver:
https: true
hostname: 'example.com'
port: 443
Change example.com to match the domain name for your PeerTube instance.
NOTE: PeerTube does not support changes in domain name. Whatever you set it as now is permanent, and changing domains will require a fresh install of PeerTube. Make sure you have a domain name registered and under your control before completing this step.
Next, find the following section inside the file:
redundancy:
videos:
check_interval: '1 hour' # How often you want to check new videos to cache
strategies: # Just uncomment strategies you want
# -
# size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
# min_lifetime: '48 hours'
# strategy: 'most-views' # Cache videos that have the most views
# -
# size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
# min_lifetime: '48 hours'
# strategy: 'trending' # Cache trending videos
# -
# size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
# min_lifetime: '48 hours'
# strategy: 'recently-added' # Cache recently added videos
# min_views: 10 # Having at least x views
...and change it so that it looks like this by removing the "#" symbols from in front of the corresponding lines:
redundancy:
videos:
check_interval: '1 hour' # How often you want to check new videos to cache
strategies: # Just uncomment strategies you want
# -
# size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
# min_lifetime: '48 hours'
# strategy: 'most-views' # Cache videos that have the most views
-
size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
min_lifetime: '48 hours'
strategy: 'trending' # Cache trending videos
# -
# size: '10GB'
# # Minimum time the video must remain in the cache. Only accept values > 10 hours (to not overload remote instances)
# min_lifetime: '48 hours'
# strategy: 'recently-added' # Cache recently added videos
# min_views: 10 # Having at least x views
NOTE: This will set up the PeerTube instance to cache videos that are trending across the network. If you prefer, you can erase the "#" symbols from different sections to cache videos that have the most views, or have been recently added instead.
If you do this, make sure that you remove the "#" symbol from in front of the "-" symbol at the top of the corresponding category (as in our example). If you forget to uncomment it, or uncomment the wrong one, it may cause problems down the road.
The rest of the configuration file can be kept as-is for now. You can explore it and attempt to change things if you feel confident, but errors in the configuration file may cause problems, so only do this if you're sure you know what you're doing.
When you're done, save the configuration file by pressing Ctrl+X, then Y and Enter.
¶ WEBSERVER SETUP
Copy the nginx configuration template:
sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
Then edit it to set the domain. Replace [peertube-domain] with the domain for your peertube server.
sudo sed -i 's/peertube.example.com/[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
Open the nginx configuration file and go through it to check that your domain name has been properly edited in:
sudo nano /etc/nginx/sites-available/peertube
As long as everything looks okay, exit the editor with Ctrl+X, then activate it:
sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
¶ SET UP CERTIFICATES
In order to have https for our PeerTube instance, we'll need to use Let's Encrypt to get a certificate. First we'll shut down nginx, then we'll request one with certbot:
sudo systemctl stop nginx
sudo certbot certonly --standalone --post-hook "systemctl start nginx"
NOTE: This certificate will expire in 90 days, so you will need to renew it before then. You can read more about how to do this from certbot's official documentation here. If you have difficulty renewing, try to shut down nginx as above before running the renew command. Don't forget to start it again after you're done, though!
After this, reload nginx:
sudo systemctl reload nginx
¶ SOME FINE TUNING
The following commands are for fine-tuning some network protocols to make PeerTube run smoother (particularly, TCP/IP). It might not be necessary, depending on the Operating System of your server, but it can't hurt to run them anyway:
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
¶ SETTING UP SYSTEMD
"systemd" is a service manager in Debian/Ubuntu (and other) Operating Systems. Not every OS has it, but we're assuming Debian/Ubuntu for this guide, so here's how to set it up for PeerTube.
Copy the configuration template:
sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
Tell system to reload its configuration:
sudo systemctl daemon-reload
And set up PeerTube to start on boot:
sudo systemctl enable peertube
¶ START PEERTUBE
Run the following commands to start the PeerTube service, and then check the logs (to make sure it's working correctly):
sudo systemctl start peertube
sudo journalctl -feu peertube
You'll see a lot of text scrolling up the screen. It's okay if you don't understand what most of it means, but you'll probably notice if there's a problem by all the Error and failure messages among them. In either case, exit the log feed with Ctrl+C.
If everything went well, congratulations! You're now the administrator of a working PeerTube instance. Confirm that everything's working by visiting your PeerTube address in a web browser.
If everything did not go well, first stop the PeerTube service:
sudo systemctl stop peertube
...and go back over the steps and configurations to make sure there aren't any mistakes. A single mistyped character or misspelled word is often all its takes to make everything stop working, so make sure this isn't the cause of your problems. You can use the sudo systemctl start peertube and sudo journalctl -feu peertube commands to check if you've successfully fixed things.
If you aren't able to fix things yourself, try asking for help from the PeerTube community, or contact us here.
¶ POST INSTALLATION
Currently, your PeerTube instance has a single user ("root"), whose password has already been autogenerated in the database, Since we don't actually know what that password is, we should probably reset it:
cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
Once you have your password, you can visit your instance via the browser and log in as "root" to access the administration panel and set up your instance. You can add new users, change your instance description, adjust settings, and more.
Be sure to join the PeerTube administrator mailing list once you've got everything working. Not only will you receive announcements about new versions, but it's also another good place to ask questions if you have any problems with your PeerTube instance.
¶ JOIN THE INSTANCE LIST (OPTIONAL)
Once you've successfully created a space for yourself and your friends, you might be interested in finding other groups to connect with. As you begin to follow more users on other instances, you'll be able to see a wider variety of content from across the Fediverse as a whole. And you'll be helping to create a more robust network for everyone else.
Check our instance list to find other groups of friends who've joined up with the 10friends Project, and consider joining the list yourself so other groups can find you.
In the future, we plan to create an automated list that instance moderators can join when they set up their server. In the meantime, this is a manually updated placeholder list. To add your instance, please contact us with your instance's information, including:
- The instance name
- Which service you're running (ie, Pleroma, PeerTube, etc.)
- What version of the service you have installed (ie, 3.0.1)
- The instance URL
- Whether or not your instance is open to new user registration
- A brief description of your instance (optional, but useful for organizing around hobbies, common interests, etc)
¶ UPDATING PEERTUBE
As new versions of PeerTube roll out, you'll want to update your instance to patch out bugs and enjoy new features. If you signed up to the mailing list, you'll receive e-mails about new versions as they come out. Otherwise, you can periodically check the Releases page of the PeerTube repository to see if a new version has been released.
NOTE: New versions of PeerTube that have "-rc" at the end of the version number are "release candidate", which means they're still undergoing testing. Unless you're interested in participating in a bug hunt or beta test, you should wait for a non-RC release before updating.
To update your PeerTube instance, go through the following steps.
First, make a backup of your SQL database and store it in /var/www/peertube/backup (creating the directory if necessary):
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 version of PeerTube:
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:
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:
cd /var/www/peertube/versions/peertube-${VERSION}
sudo -H -u peertube yarn install --production --pure-lockfile
Copy over the new default configuration template:
sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
And compare it to your configuration file to see what differences there are:
diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
The output on your screen is a line-by-line comparison of the template (production.yaml.example) and your actual config (production.yaml), highlighting the differences between the two. Some parts of the file are obvious going to be different (for example, hostname: 'example.com' in the template versus your real domain in the actual config, or any of the changes we made in the Editing Configuration step).
Other differences, however, may be important new configuration changes. If you see any, you'll want to go into your actual configuration file and edit those changes in:
sudo nano /var/www/peertube/config/production.yaml
When you're finished, save changes and exit with Ctrl+X, Y, and then Enter.
Now have PeerTube point to the latest version:
cd /var/www/peertube
sudo unlink ./peertube-latest
sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
Next, check for changes in the nginx configuration:
cd /var/www/peertube/versions
diff "$(ls --sort=t | head -2 | tail -1)/support/nginx/peertube" "$(ls --sort=t | head -1)/support/nginx/peertube"
...and in the systemd configuration:
diff "$(ls --sort=t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls --sort=t | head -1)/support/systemd/peertube.service"
If differences showed up in either, or both, then you'll want to restart them.
For nginx:
sudo systemctl reload nginx
For systemd:
sudo systemctl daemon-reload
Finally, restart PeerTube:
sudo systemctl restart peertube && sudo journalctl -fu peertube
From here, the procedure is the same as the Start PeerTube section above. If you see errors, stop peertube and go over the configuration changes again, and get in touch with the PeerTube or 10friends community if you need help.
If you want to roll back to a previous working version, you can point back to it and restore your SQL backup with the following commands. Change [old-version-number here] to the version number you had before updating, and [sql-backup-file-name-here] to the name of your sql backup. If you're not sure what it is, check in /var/www/peertube/backup:
OLD_VERSION="v[old-version-number-here]" && SQL_BACKUP_PATH="backup/[sql-backup-file-name-here].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 postgres "$SQL_BACKUP_PATH"
sudo systemctl restart peertube
¶ FURTHER READING
As a PeerTube administrator, it's a good idea to read up on how to manage and maintain your server. The official PeerTube documentation has guides and instructions on everything you might want to do, and the official support channels can answer any specific questions you have. We're also happy to help where we can (and you should feel free to contact us here), but official PeerTube support channels are probably the best place to start.