Using PeerTube

To start using PeerTube, first find the instance that best suits you, from the official tracker [3]. In this phase, never forget that PeerTube was also created to let any video hosting organization deny (or allow) whatever they wanted on their own server. Therefore, even before browsing the videos of each instance, check out its About page very carefully, to find out what its policies are. Once you have found a proper home for your own content, or just the place with the most interesting videos, choose a user name, create an account, and wait for the email confirmation. When that comes, log in and configure your account, starting with notifications: You can decide whether to be informed right away, or not, about new videos, new followers, new comments to your own content, or your mentions in somebody else's comments.

Next, you will need to declare whether you want to see videos only in certain languages, see or hide sensitive material, and enable or disable autoplay. Another important decision is about using WebTorrent in your browser. If you do it, you will exchange parts of each video you download from PeerTube with other, simultaneous viewers of the same video. This will improve playbacks, both yours and theirs, but also expose your IP address to unknown third parties. Of course, it's up to you to decide whether you like this or not.

Once you are done with the basics, set up your own channels. PeerTube channels work like independent playlists, each with a different topic. The "independent" part means that a PeerTube user cannot subscribe to "whole" accounts of other users. The only way to see every video from a user who set up several channels would be to subscribe to every one of them separately.

This may seem like a bit of a hassle, and sometimes it is. But it also is one more support to avoid distraction. Subscription, in fact, makes you automatically see everything the users post in the channels to which you subscribed (Figure 3).

Figure 3: Customize PeerTube by finding and subscribing to interesting channels.

You can find videos about specific topics, inside your instance and all the others federated with it, by typing relevant keywords into the search box of your main PeerTube window (Figure 4). You can then subscribe to the channels that posted those videos by simply visiting them and then clicking on the corresponding button (Figure 5). (For the record, you can also perform most of the main functions of the PeerTube web interface in the third party Android app called Thorium [4]).

Figure 4: Type any keyword in the search box, and discover all relevant results in all PeerTube instances federated with yours.

Figure 5: You can subscribe to PeerTube channels in several ways: from PeerTube, from Mastodon, or with good old RSS!

If you already know the URL of a channel you want to subscribe to, you may just paste that URL either in your browser address bar, or in the PeerTube search box. Of course, this procedure works only when you had already discovered, in some other way, where to find interesting videos. As I already said, in a loose, continuously changing federation of independent instances, nobody goes out of their way to take note of what you like and make suggestions.

A dirty but simple trick suggested by the PeerTube website solves this problem, at least partially: Periodically check out the PeerTube's instance tracker [3], sorting the results by platform version, as this may make it easier to spot newer instances.

A completely different way to make PeerTube your one-stop interface to all the videos you care about is the Firefox and Chrome extension called PeerTubeify [5]. As shown in Figure 6, whenever you watch a video on YouTube, if there is a video with the same title on the PeerTube instance you told it to check, PeerTubeify will display a clickable thumbnail that will lead you straight to that video.

Figure 6: Thanks to PeerTubeify, only the copy of Firefox on the right can lead you to PeerTube copies of videos hosted on YouTube.

You can upload videos to your PeerTube account from different sources: your own computer, PeerTube torrents, or just normal URLs of video files. In the latter case, the files must be raw MP4 video, or any other format supported by the youtube-dl utility. Besides language, tags, and privacy settings, Figures 7 and 8 show two parameters that deserve particular attention: licenses and categories. The reason is that, in both cases, you can only choose among the options predefined by your PeerTube administrator. On the other hand, all PeerTube instances support independent video creators: You get a dedicated box to describe where and how your followers may send money or support you in any other way.

Figure 7: PeerTube administrators decide which licenses are acceptable on their servers.

Figure 8: Even categories are decided by PeerTube administrators.

When you are done with publishing a video, you can finally preview it inside PeerTube (Figure 9), choosing among different resolutions and playback speeds. Depending on the policy of the instance you subscribed to, you may experience the same problem I encountered with the test account I created for this tutorial: All your videos may be auto-blacklisted for several days, until a moderator has time to check and approve them. That's the price to pay for not being wrongly blacklisted by algorithms, I assume.

Figure 9: Watching videos in PeerTube: Note the automatic moderation warning!

Running Your PeerTube Instance

In theory, the need to avoid blacklisting and the other limits for PeerTube end users mentioned above are excellent reasons to set up your very own instance. After all, that's the whole point of free and open source software, isn't it? In practice – and I write this with full consciousness of how weird it is to give such advice in a free software tutorial – think twice before making such a move.

The reason is that, as good and necessary as it is, PeerTube has one objective constraint that is not its fault at all, plus (at time of writing) a more critical sore spot, that will surely heal as the project matures but is not negligible right now.

The objective constraint is hardware-related. According to the PeerTube developers, the main demo server [2], which has 2 vCores (the minimum recommended to enable transcoding, which is crucial to optimize bandwidth) and 2GB of RAM, consumes on average less than 35 percent of CPU cycles and less than 150MB of memory.

Those are good figures, but only tell half the story. Video needs much, much more disk space than other content and much more bandwidth, too. If you want to offer a reliably decent service, forget the cheap hosting packages that would be more than enough to run almost any other type of website.

The sore spot is in the software. PeerTube's end-user interface is very simple and pleasant to use. Installing and configuring PeerTube and its environment is much more complicated and unpredictable than any other package I have installed in the last five years.

PeerTube has a lot of critical dependencies [6], many of which are not exactly simple to install and configure in the first place: PostgreSQL, NGINX, Node.js, npm, Yarn and an up-to-date version of g++ to run it, FFmpeg, the Redis in-memory data store, the Traefik reverse proxy, and more.

Besides, it seems that each of those packages must be exactly of a certain version, and configured exactly in one, and one mode only, needed for PeerTube. The final result is also likely to depend on the previous, specific configuration of the Linux distribution that hosts PeerTube.

Even Docker containers, the default solution for this kind of problem, may not be enough for PeerTube. Some documentation is available [7, 8], but it is not sufficient, in my opinion. When testing Docker containers for PeerTube, I have encountered problems I never had with containers for other packages, from not having a compatible version of docker-compose to what seemed not fully documented dependencies on packages (e.g., a PostgreSQL server) external to the container.

Now, don't get me wrong here: PeerTube is great, its developers are doing a great job, and, in spite of what I just wrote, it is possible to get PeerTube up and running on Linux, without being a hard-core developer. I am only saying that it is a longer, much more complex process than installing stuff like WordPress or Drupal. With PeerTube, there are many more parameters and steps to get exactly right. For all these reasons, plus lack of space, I don't feel comfortable describing a complete procedure that may work only on a server identical to mine, and which, even in that case, may be half obsolete anyway by the time you read this.

Instead of doing that, I will conclude this tutorial with advice less specific than a complete installation procedure that should still save you a lot of time if you decide to install PeerTube.

First of all, check if there is one single Docker image that contains everything needed to run PeerTube (including the scripts mentioned below), already preconfigured and fully customizable with only one, fully documented environment file. If such a container exists, try that first, to get familiar with PeerTube and its administration procedures.

When you feel ready, go for a real installation, but in this way: Ask on the PeerTube forum [9] who is already running the current version of PeerTube without problems and then just clone that full Linux installation, from the kernel up, on a virgin virtual or physical server, reserved exclusively to PeerTube. A more expensive alternative, but worth the money if you can afford it, would be to ask on the same forum for Web hosting providers that officially support PeerTube installations.

Post-Install Tips

First, be prepared for migration, before you even start using PeerTube. There is no real "data ownership" if you cannot move to any other server, in any moment, with zero or minimal loss of service, and doing that with PeerTube may be as complex as installing it. Detailed migration instructions are available on the website [10], but, just as with installation, fully cloning your whole PeerTube/Linux installation to a new machine may be the best solution.

Second, decide very carefully with which servers to federate, and regularly check whether their policies change. You can add or remove instances to follow in the Manage Follows | Follow tab of the Administration panel. There also is a script, called PeerTube autoDiscover [11] that can facilitate the discovery of new instances.

Third, regularly check which instances follow yours, as you may want to block them if your respective policies are too different. You need to do this because, at least at time of writing, PeerTube automatically accepts requests to be followed.

Fourth, study and take advantage of the PeerTube maintenance scripts [12], which you can launch on the server or even remotely, from your laptop.

For example, once you are sure that your instance is configured properly, you can automatically load both your own and third-party videos inside it. In the latter case, of course, you must comply with their licenses. To upload videos from your computer straight into a PeerTube account, use the peertube-upload.js tool [12].

Videos already hosted online, instead, are the target of another script, called peertube-import-videos.js [12]. This utility can upload to PeerTube all the videos of any account on YouTube, Vimeo, Dailymotion, or any other website supported by the youtube-dl tool. The script also knows how to avoid downloading the same video twice, so you can even run it as a cron job, to keep your instance always up to date.

Fifth, keep video transcoding under control. Efficient video streaming heavily relies on transcoding (i.e., converting videos in formats or resolutions more suitable for streaming than their native ones). The PeerTube "server tools" [12] for this task are called create-transcoding-job.js and prune-storage.js. The first forces transcoding of already existing video files. The second finds and deletes all the temporary files created by some transcoding procedures, recovering space on your server.