Freer Video Hosting and Sharing

Tutorial – PeerTube

Article from Issue 232/2020

With PeerTube you can self-host your videos without the limitations embedded in YouTube and similar platforms.

PeerTube [1] is a free and open source video hosting and sharing platform with great ambitions. With PeerTube, everybody can set up a website where all registered users can upload, organize, and share as they like all their videos, without the constraints and risks that plague platforms like YouTube.

In this tutorial, I will describe the main components of a full PeerTube installation, how they work, and above all the pros and cons of running your own instance versus just registering as a user on somebody else's instance. This is necessary, because ignoring PeerTube would be a serious error, but it would also be a mistake to jump into it without clear ideas of what's involved.

I will also outline how to set up and use a PeerTube user account on existing instances, and how to prepare yourself for installing your own.

PeerTube Architecture

The core of PeerTube is a Node.js application, distributed under the AGPL v3 license. In practice, in order to work, a PeerTube-based video hosting website requires a whole bundle of free software. For example, PeerTube needs the Yarn package manager and a PostgreSQL database server to store user parameters and video metadata. Under the hood, the FFmpeg transcoder converts video to the open formats most suitable for efficient streamings in multiple resolutions.

Equally important are the NGINX web server, and the Certbot/Let's Encrypt system for handling the SSL certificates that allow encrypted connections to a PeerTube instance. The WebTorrent protocol allows multiple simultaneous viewers of the same video to download and share different parts of it among themselves, in order to not overload the server.

Now, if this were the whole story, PeerTube would be just a do-it-yourself, standalone, web-based video manager: a nice and useful project for sure, but nothing really special.

But the real value of PeerTube is not its looks, ease of use, or how well it transcodes video clips: It is federation. This, as shown in Figure 1, is the ability for any single instance to show videos uploaded to other instances, side by side with the ones hosted locally. Technically, this is done through the ActivityPub protocol, which is used in the same way by Mastodon, the most popular open source alternative to Twitter.

Figure 1: The highlighted links show how one PeerTube account gives access to videos on different servers.


By automatically exchanging notifications and metadata with other instances, even a small installation of PeerTube on a cheap, low-end server may show its users one single catalog of thousands of videos. Some day, ActivityPub should allow you to browse even MediaGoblin instances in the same way! In general, any application that supports ActivityPub may syndicate content from PeerTube instances.

You can get a very good feeling for how all this works in practice by visiting a PeerTube demonstration server [2], and then any of the public instances registered in the official tracker [3].

The same tour will also show how its architecture gives every administrator or (to a much smaller extent) simple user of PeerTube much more freedom and other advantages than are available today on platforms like YouTube.

A PeerTube instance frees all its own users, as well as everybody else browsing its videos, from automated tracking and profiling (i.e., from advertising or surveillance). Besides, no corporate policy (within the limits of law, of course) can forbid a PeerTube administrator to host any video or take it offline without explanation or excuses. Inside PeerTube, no flawed copyright-enforcement algorithm may automatically erase your content and maybe make you lose money, too.

At the same time, as a PeerTube administrator, only you decide what is acceptable content and user behavior on your instance, or with which other servers to federate. As an administrator, you can also enable or disable user registration, moderate uploaded videos, and set user quotas.

If you don't want to or cannot be a PeerTube administrator, but just want to watch videos without banners and tracking, don't worry! Even simple users of Peertube instances can enjoy many of those freedoms. There already are lots of independent instances, and many more will surely appear in the near future, each with its own, possibly unique terms of service, but never as addictive as YouTube. This means that each individual, whatever her needs are, can sooner or later find an instance that suits her well.


Unlike YouTube, PeerTube instances are not designed to lure you into watching as many videos as possible, in order to profile you and maximize advertising profits. Whether local or federated, PeerTube just displays videos as they appear (Figure 2). Above all, federation is voluntary: If you subscribe to one PeerTube instance, but most of the videos you would find interesting are published on another instance, they will automatically show up in your original PeerTube account only if both the administrators involved agreed to federate their instances.

Figure 2: The local content of a PeerTube instance has its own separate tab.

On one hand, this can make discovery of new, interesting content sensibly slower than it is inside YouTube. Surely, we could and would still use search engines to discover video content. Still, in a PeerTube world, we may likely end up watching less video than today – maybe much less. If you think about how much time we waste on YouTube as a society, this comes out as a feature, not a bug.

At the same time, as long as federation happens at instance level, the only way for you to get seamless access to any PeerTube instances you may be interested in is to set up your own, which, as I will argue shortly, still looks pretty far from being an easy task. I propose a solution to this problem at the end of the tutorial.

Next on the list of PeerTube cons is performance: A major reason why YouTube became so popular is that it can spend billions on bandwidth and state of the art, constantly optimized content delivery networks. The video streaming from a PeerTube instance, unless its owner spends significant money on connectivity, will statistically be slower and more subject to glitches than that from YouTube, even if that instance only hosts a few videos. Please note that WebTorrent won't change that: Torrents work as advertised only when many people want to download the same file, in the same moment.

Last but not least, with great power comes great responsibility. Whoever runs a PeerTube instance becomes not only the first target of any copyright complaint, but also the sole arbiter of any fight among users. For some users, this will be a nonissue, for others a showstopper. Now that you have been warned, let's see what you may do with PeerTube, first as a normal user, then with your own instance.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • PeerTube

    PeerTube, the Fediverse's video platform, offers a decentralized, open source way to watch videos and live stream your own content. We'll show you how to get started and even set up your own instance.

  • Tutorials – Docker

    You might think Docker is a tool reserved for gnarly sys admins, useful only to service companies that run complicated SaaS applications, but that is not true: Docker is useful for everybody.

  • A Federated Reddit Alternative

    With Reddit closing off access to its API, it is time to look to the Fediverse for an alternative.

  • Tube Archivist

    Tube Archivist indexes videos or entire channels from YouTube in order to download them with the help of the yt-dlp tool.

  • Introduction

    This month in Linux Voice.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More