1. What PeerTube Actually Is
PeerTube is a free and open-source video platform that refuses the single-server model that defines YouTube, Vimeo, and Dailymotion. It was started in 2017 by a developer who goes by Chocobozzz as a peer-to-peer alternative to YouTube, and since 2018 its development has been carried by Framasoft, a small French non-profit association founded in 2004. Framasoft is deliberately tiny — a dozen employees and a few dozen volunteers — and is funded almost entirely by donations. That funding model matters: no venture capital means no pressure to monetize your attention, your audience, or your uploads.
The repository, Chocobozzz/PeerTube, carries roughly 15,000 GitHub stars and is licensed AGPL-3.0. It is written mostly in TypeScript and Node.js, with PostgreSQL for the catalogue and accounts, Redis for the job queue, ffmpeg for transcoding, and optional S3-compatible object storage for the actual video files. Because it speaks ActivityPub, the same open protocol behind Mastodon and the wider Fediverse, a PeerTube instance is not an island. It is a node in a network of independently run video servers that can follow one another, mirror content, and share audiences without any central company in the middle.
The simplest way to understand PeerTube is to flip the mental model you have of YouTube. On YouTube, Google owns the storage, the discovery, the algorithm, the ad placement, the account system, and the rules of who gets to stay. On PeerTube, you own the storage, you choose the rules, and discovery happens through federation and opt-in following rather than a single global algorithm. You can run an instance for your family, your classroom, your union, your band, or your company, and those videos remain fully playable from your own domain even if every other instance disappears tomorrow.
2. The Problem PeerTube Exists to Solve
The complaint that motivates PeerTube is not "video hosting is hard." It is "video hosting is centralized, and centralization has consequences." When one corporation controls the dominant video platform, it sets the moderation policy, the monetization split, the recommendation logic, and the terms under which you are allowed to exist on it. Channels are demonetized, age-restricted, region-blocked, or deleted with little recourse. Entire categories of speech are pushed off the platform not because a law changed but because an advertiser complained. Creators build an audience for years and then watch that audience become a liability the moment the platform decides the audience is not profitable enough.
PeerTube answers this with architectural disaggregation. There is no global account system to ban you from. There is no single recommendation engine deciding whether your video is seen. Each instance administrator sets their own moderation rules, their own registration policy, and their own content guidelines. If you do not like the rules on one instance, you are not locked into it — you can run your own. That is the core data-sovereignty promise: the means of publication are not rented from a party that can revoke them.
The second problem is bandwidth and cost concentration. A small creator who posts a video that goes viral on a self-hosted server traditionally pays for every byte served. PeerTube attacks this with peer-to-peer playback: viewers who are watching a video also help relay pieces of it to other viewers, which lowers the load on the origin server. For a small instance operator, this is the difference between a popular video taking down your server and a popular video simply costing a bit more in storage. It is not a perfect system, and we will be honest about its limits later, but it is a genuine structural innovation that no centralized platform offers its users.
3. How PeerTube Works Under the Hood
A production PeerTube deployment is not a single process. At minimum you are running five cooperating pieces, and on larger installs you split some of them onto dedicated machines.
The web application is a Node.js server. As of the 8.x series it targets Node.js 22. This process handles the API, the front-end, federation with other instances, and the scheduling of background jobs. It is relatively light on CPU outside of transcoding because most of the heavy lifting — video encoding — is delegated to separate runner services.
PostgreSQL is the system of record. It stores accounts, video metadata, federation state, comments, playlists, and the activity log that keeps your instance in sync with the rest of the Fediverse. Framasoft is explicit that you should use PostgreSQL from day one; the SQLite path exists only for quick experiments and performs poorly the moment you participate in federation.
Redis backs the job queue. Every transcoding task, every import, every federation delivery attempt is a job that passes through Redis. On a small instance Redis and PostgreSQL can live on the same machine; on a busy instance they deserve their own resources.
ffmpeg does the actual video work. When someone uploads a file, PeerTube can transcode it into multiple resolutions so that viewers on a phone, a laptop, or a smart TV all get a sensible stream. That transcoding runs on a runner, which can be the same machine or a separate worker. This is the single most resource-hungry part of the stack, and it is where most of your real compute cost hides.
Object storage is where the videos themselves live in a sane deployment. The local disk volume holds only thumbnails, previews, storyboards, and upload scratch. The multi-megabyte video files go to an S3-compatible bucket — MinIO in your rack, or a hosted S3, or Backblaze B2, or Hetzner Object Storage. Keeping video off the system disk is what makes the platform survivable as your library grows.
4. Federation and the Fediverse
Federation is the feature that makes PeerTube more than "a private video site with extra steps." Because PeerTube implements ActivityPub, your instance can follow other instances. When you follow an instance, its public videos appear in your explore page and your users can subscribe to its channels. Federation is asymmetric: instance A can follow instance B without B following A back. This lets small communities cluster around shared interests without anyone needing to be globally dominant.
Crucially, every video is stored only by the instance that published it. Federation does not copy every video everywhere. Instead, it shares metadata and, optionally, allows administrators to mirror specific videos or entire friend instances. Mirroring is a deliberate act: you choose to cache another instance's content on your server so that your viewers get it faster and the origin server bears less load. This creates the cooperative bandwidth incentive that the project is built around.
Discovery is the part that takes adjustment. There is no single global search box that indexes every video on every instance the way YouTube's search indexes everything it hosts. Instead, each instance shows what it knows about through its own follows and through Sepia Search, Framasoft's opt-in meta-search engine that crawls participating instances. This fragmentation is a feature to some — it resists centralized surveillance and algorithmic manipulation — and a weakness to others, because a brand-new instance with no follows has a quiet front page until its administrator builds connections.
5. Peer-to-Peer Playback
The headline PeerTube trick is that playback is not purely client-to-server. When a viewer watches a video, their browser can also become a relay, sending chunks of that video to other viewers through WebRTC peer-to-peer connections layered on top of HLS. The server sends the first copy; the swarm distributes the rest. For an instance operator, this can dramatically cut egress cost when a video is popular, because much of the delivery is viewer-to-viewer rather than server-to-viewer.
A note on history: older PeerTube versions used WebTorrent for this P2P layer. Beginning with version 6, the project moved away from WebTorrent and toward the current HLS plus WebRTC P2P approach. If you read older tutorials mentioning WebTorrent, they are describing a mechanism that no longer applies to modern releases.
P2P is not magic and it is not free. It works best in browsers that support the required WebRTC data channels, and it depends on enough concurrent viewers being present to form a useful swarm. A video with exactly one viewer gets nothing from P2P because there is no one to share with. A video with thousands of concurrent viewers benefits enormously. It is also worth remembering that P2P shifts bandwidth rather than eliminating it: the bytes still travel, they just travel between users more often than between a user and your origin.
6. Live Streaming
PeerTube is not only for uploaded files. It supports live streaming through RTMP ingest. From OBS or any RTMP-capable client, you point the stream at the RTMP endpoint your instance exposes, paste the stream key, and go live. Your viewers watch through the normal web player, and the live stream can be recorded and saved as a regular video afterwards.
Live streaming raises the same resource questions as on any platform: ingest needs stable upload bandwidth, transcoding of the live feed needs CPU or GPU, and a popular live event needs enough network capacity to serve everyone. The federation and P2P features apply here too, so a well-followed instance can absorb a spike in live viewers more gracefully than a lone server could. For organizations running regular live events — town halls, classes, concerts — this is one of the more compelling reasons to self-host rather than rent a proprietary streaming service that charges per viewer-hour.
7. Transcoding: The Real Cost Center
If you remember one operational fact about PeerTube, make it this: transcoding is where the money and the wait time live. When a video is uploaded, PeerTube can produce several resolutions — 360p, 480p, 720p, 1080p, and so on — so that every viewer gets a stream matched to their connection. Each rendition is encoded separately, and encoding runs at roughly real time per rendition on a CPU runner. A one-hour upload transcoded into four resolutions costs about four hours of runner CPU. A ten-minute clip into four resolutions costs about forty minutes. That math scales linearly with your upload volume.
You have three ways to pay this bill. First, you transcode on the same machine as the web app, which means you need enough CPU headroom (the documentation suggests 8 vCPU and 8 GB RAM if you transcode locally on a busy instance). Second, you run dedicated transcoding runners, separate worker machines that register with your instance and pull jobs from the Redis queue. Third, you pre-transcode or accept a single resolution and skip the multi-rendition ladder. Hardware acceleration through Intel Quick Sync or NVIDIA NVENC can cut the time dramatically if your host exposes it, but not every VPS gives you a usable GPU or Quick Sync path, so plan for software encoding unless you have verified acceleration.
The practical takeaway: the "cheap" PeerTube you run for a quiet family instance costs almost nothing in transcoding because nobody is uploading much. The PeerTube you run as a community video hub lives or dies by how you architect the runner tier, because that is the one part of the stack that grows with your actual usage rather than your user count.
8. Storage Architecture: Disk Versus Object Storage
PeerTube gives you a choice about where video lives, and the choice defines how the system scales. The simplest deployment keeps everything on the local filesystem of the PeerTube server. This is fine for a few dozen videos on a large disk, but it couples your storage growth to your compute server and makes migration painful. The recommended production approach is S3-compatible object storage: the web volume stays small (thumbnails, previews, storyboards, scratch), and the videos go to a bucket you control.
Object storage has two big advantages. It decouples capacity from compute, so you can expand a bucket without resizing your server. And it is portable: you can point PeerTube at MinIO in your basement, at Backblaze B2, at Hetzner Object Storage, or at AWS S3, and the application does not care which one you picked. If you later migrate, you move the bucket, not the whole machine.
The catch is egress. Many object storage providers charge little for storage but significantly for data leaving their network. A video that gets watched heavily can generate egress bills that dwarf the storage bill. This is exactly the cost that P2P playback is designed to blunt, and it is why serious PeerTube operators pair object storage with a CDN or a bandwidth-friendly provider. We will put real numbers on this in the cost section.
9. Installation: Docker Compose in Practice
The supported path to a production instance is the official Docker Compose file shipped in the repository under support/docker/production. You clone the repo, copy .env.example to .env, and then set a handful of values before bringing the stack up. The two you must get right are PEERTUBE_WEBSERVER_HOSTNAME and PEERTUBE_SECRET. The hostname becomes baked into every federated identifier on your server — your channels and videos are addressed as @
[email protected] — and it cannot be changed later without effectively starting over. Pick the final domain first, not after a test run. The secret should be a long random string generated with openssl rand -hex 32.
After editing the environment file you run docker compose up -d and watch the logs with docker compose logs -f peertube. Registration is off by default, which is the safe choice; you log in as the root account using the password you set, create accounts for real users once moderation is configured, and only then consider opening registration. A reverse proxy that terminates TLS is required in front of the stack, and unless you keep video on local disk you also need object storage configured before you go live.
10. Reverse Proxy and TLS
PeerTube expects to sit behind a reverse proxy that handles HTTPS. The well-trodden options in the self-hosting world are Nginx, Caddy, and Traefik, and all three work. The proxy needs to forward both the standard HTTPS port and the federation port (8448) correctly, and it must serve the .well-known/matrix-style discovery files that let other instances find you — though for PeerTube the relevant well-known files are the nodeinfo and the webfinger endpoints that ActivityPub relies on. If federation is broken, the proxy and DNS configuration are the first places to look.
TLS certificates are free through Let's Encrypt whether you use Caddy's automatic issuance, Traefik's ACME integration, or certbot in front of Nginx. There is no reason to pay for certificates for a self-hosted instance. One detail that bites newcomers: your proxy must allow large request bodies, because video uploads are large. In Nginx you raise client_max_body_size; in Caddy you set the request body maximum. If uploads fail with opaque errors, an undersized body limit at the proxy is the usual culprit.
11. Configuration Essentials
A handful of settings decide whether you have a server or an incident. The signing key, stored as a .signing.key file in your data directory, is what proves to other instances that messages genuinely come from you. Lose it and federation trust breaks until other servers pick up a new key; back it up with the rest of the data directory. Per-user video quotas, set with PEERTUBE_USER_VIDEO_QUOTA, prevent a single user from filling the bucket overnight; a value of -1 means unlimited, which is rarely what you want on a multi-user instance. Maximum upload size, both in PeerTube and at the proxy, governs the largest single file anyone can post.
Registration policy is a judgment call. Open registration invites abuse; closed registration invites support tickets. Many operators start closed, create accounts manually or via invite, and only open registration behind good moderation tooling. SMTP must point at a real mail relay before you go live, because account confirmation and password resets depend on it. None of these are exotic, but together they are the difference between a usable instance and a spam farm.
12. Honest Limitations
No honest review of self-hosting software is complete without its weak points, and PeerTube has several worth naming plainly.
First, discovery is fragmented. A new instance with no follows and no Sepia Search listing is quiet. There is no central algorithm to surface you, which is ideologically consistent but practically cold for creators who expect an audience to appear.
Second, the administrative burden is real. You are responsible for the server, the database, the object storage, the proxy, the certificates, the upgrades, the moderation, and the backups. Framasoft ships the software; it does not run your instance for you.
Third, transcoding is expensive in CPU terms, as covered above, and there is no way around the fact that multiple resolutions cost multiple encode passes.
Fourth, P2P playback helps at scale but does nothing for a long tail of videos watched by one person at a time, and it depends on browser support and viewer concurrency.
Fifth, the mobile experience has historically lagged the web. There are apps, but they are not as polished or as universally available as the YouTube app people are used to.
Sixth, single-instance durability is on you. If your server dies and your backups are stale, your videos are gone, because federation mirrors only what other admins chose to mirror.
Seventh, migration of an existing YouTube audience is not a one-click import. Bridges and import tools exist for some sources, but you are realistically re-publishing content you have the rights to, not teleporting a channel and its subscribers.
Eighth, version upgrades occasionally require database migrations and careful reading of release notes, and because federation is a shared protocol, lagging too far behind can cause interop issues with newer instances.
None of these are fatal, but they are the reasons PeerTube is a better fit for communities and determined individuals than for someone who wants video hosting with zero effort.
13. Real Self-Hosting Cost Numbers
Let us put actual figures on running PeerTube, because "it's free and open source" hides the infrastructure bill. All numbers are 2026-era estimates in US dollars and will drift with provider pricing, but the shape is stable.
A small personal or family instance can live on a modest VPS. A contabo-style plan with 4 vCPU, 8 GB RAM, 50 GB SSD, and generous traffic runs around six dollars a month. A Hetzner CX22-class instance with 2 vCPU, 4 GB RAM, 40 GB SSD, and 20 TB traffic is about five dollars a month. Either is enough for a light instance that transcodes on a separate runner or off-peak. Budget roughly six to fifteen dollars a month all-in for compute if you keep transcoding modest.
Object storage is where the variable cost lives. Backblaze B2 stores at about six dollars per terabyte per month and egress runs about nine dollars per terabyte. Hetzner Object Storage bundles a terabyte into roughly six dollars a month and charges a few cents per extra gigabyte. AWS S3 is about two and a third cents per GB per month for storage and nine cents per GB for egress. For a library of a few hundred hours of video at roughly two to seven gigabytes per hour depending on renditions, storage might be five to thirty dollars a month, while egress only bites when videos are actually watched a lot — which is exactly when P2P helps.
Transcoding, if run on a dedicated runner, is billed in compute time. A one-hour video into four renditions is about four hours of CPU. On a ten-dollar-a-month runner that is a few cents per upload; on a heavy-upload community instance it becomes a real line item, which is why many operators cap resolutions or schedule transcoding.
Add a domain at about one dollar a month and free TLS certificates, and a realistic small-instance total is roughly eight to twenty-five dollars a month, almost entirely infrastructure, with no per-seat fee and no revenue share taken from you. Compare that to "free" YouTube, where the price is paid in algorithmic dependency, audience lock-in, and a forty-five percent cut of ad revenue plus the constant risk of demonetization or removal. For creators who value ownership, the paid-but-yours model is the rational one.
14. Where Your Data Goes and Data Sovereignty
This is the section the entire project is built around, so it deserves precision. When you self-host PeerTube, your videos are stored in the bucket or filesystem you configured — not on Google's servers, not on a CDN you do not control, not in a proprietary format you cannot read. The metadata — accounts, video descriptions, comments, playlists, federation state — lives in your PostgreSQL database on hardware you chose. Redis holds the job queue on that same or adjacent infrastructure. The signing key that authenticates your instance to the network is a file you possess and must back up.
Federation does introduce controlled sharing. When your instance follows another, or another follows you, the relevant public metadata and, where mirrored, video copies move between instances according to the administrators' choices. This is not surveillance leakage; it is the explicit, opt-in mechanism that makes a decentralized network function. You can run a fully private instance that federates with no one, in which case nothing leaves your boundary except the video bytes your own viewers fetch.
Privacy caveats to state honestly: viewer IP addresses touch your server and your object storage when P2P is insufficient, so standard web-server logging considerations apply and you should have a privacy policy and retention plan. Comments and accounts are personal data under regulations like GDPR, and because you are the controller, export and deletion requests are your responsibility to honor from your own database. The AGPL license itself reinforces sovereignty: anyone who runs a modified version as a network service must publish their changes, so the code handling your data stays inspectable rather than hidden behind a proprietary black box.
Backups are the unglamorous half of sovereignty. A verified backup of the PostgreSQL database, the Redis data if needed, the signing key, and the object storage bucket is what turns "I control my data" from a slogan into a fact. Without tested restores, you control your data right up until the moment the disk fails.
15. Performance and Scaling
PeerTube's scaling story is different from a monolithic platform because federation and P2P offload work that would otherwise land on your origin. The classic back-of-envelope number: a server with a one gigabit-per-second uplink can theoretically serve around two hundred concurrent viewers of a five-megabit-per-second 1080p60 stream, because one gigabit divided by five megabits is two hundred. In practice you plan for rather less, because overhead and spikes are real, but the order of magnitude holds.
When you need more than your uplink allows, federation helps. If other instances follow you and choose to mirror popular videos, their servers absorb much of the delivery load for their own viewers. This is the cooperative bandwidth model in action and the reason a small instance can survive a popular video far better than a similarly sized traditional self-hosted streamer could. For very large deployments, Framasoft documents redundancy and runner separation, and at that scale you are running PostgreSQL and object storage on dedicated, fast SSD hardware with the web tier behind a load balancer.
16. Moderation and Administration
Running a public instance means accepting that moderation is a feature, not an afterthought. PeerTube ships tools for user management, instance-level and account-level blocking, comment moderation, and quota enforcement. Because federation is open, an instance that federates widely will see content from other servers, and administrators can choose which instances to follow, which to silently block, and which to quarantine. The trade-off is real: tight moderation protects your community but increases your workload; loose moderation reduces your workload but imports other people's problems.
For a single-operator instance, the pragmatic path is to start closed, build a small trusted user base, and only open registration behind solid moderation settings and quota limits. The administrative interface is mature and covers most daily tasks without dropping to the command line, but you should still be comfortable with docker compose, logs, and database backups before you invite the public.
17. Plugins and Theming
PeerTube supports plugins and themes through a marketplace accessible from the administration interface. You can install plugins that add external authentication (LDAP, OpenID Connect), change the player behavior, add analytics, or integrate with other services, and you can apply themes that reskin the front-end to match your organization. This extensibility is part of what keeps a self-hosted instance from feeling like a barebones knockoff: with a little effort the front page can look like a purpose-built site for your community rather than a generic clone.
The caution is the same as for any plugin ecosystem: every plugin is code running in your stack, so install from reputable sources, keep them updated, and be aware that a misbehaving plugin can affect performance or compatibility across upgrades. A lean plugin set is usually the right call for a small instance.
18. Migrating From YouTube and Imports
A common question is whether you can move a YouTube channel to PeerTube. The honest answer is that there is no lossless, one-click teleport of an audience. PeerTube supports imports over HTTP, torrent, and channel synchronization for some sources, but these are tools to re-publish content you have the rights to, not to migrate subscribers. Your subscribers are Google's accounts, not yours, and there is no portable identity that carries them to your instance.
What you can do is re-upload your own videos, announce the new instance on your existing channels, and let interested viewers follow you on the Fediverse. Over time a chunk of your audience may prefer an ad-free, algorithm-free home, especially if you explain the ownership argument. The migration is a marketing and relationship project more than a technical one, and that is the part many creators underestimate.
19. Backup and Disaster Recovery
Backups deserve their own section because they are the difference between sovereignty and delusion. At minimum you need four things backed up on a schedule and tested by a restore: the PostgreSQL dump, the Redis persistence if your deployment relies on it, the signing key and full data directory, and the object storage bucket contents. Store backups off the same machine and ideally off the same provider, because a server failure that also destroys the only backup is functionally the same as no backup.
Test the restore path before you need it. A dump you have never restored is a hope, not a backup. For a small instance a nightly database dump plus periodic bucket synchronization to a second location is a reasonable baseline; for a community instance you should tighten the interval and verify integrity. Remember that federation mirrors are not a substitute for your own backup, because mirrors are at the discretion of other admins and can be removed.
20. Security Hardening
A public video server is an internet-facing service and should be treated like one. Keep PeerTube and its dependencies patched; the project ships frequent releases and CVEs do get fixed, so running an old version is the easiest way to get owned. Run the stack behind your reverse proxy with TLS, restrict admin access, use a strong root password or better yet SSO through an identity provider, and consider putting the admin interface behind additional network controls. Keep object storage credentials scoped tightly and rotate them if they may have leaked. Monitor logs for abuse patterns, because an open upload endpoint will eventually attract automated junk. None of this is unique to PeerTube, but the fact that you are now the operator means these responsibilities are yours rather than Google's.
21. PeerTube Against the Alternatives
It helps to place PeerTube beside the other self-hosted options this blog has covered. Jellyfin is a superb self-hosted media server, but it is built for your own library streamed to your own devices, not for public publishing or federation with strangers. Nextcloud can store and serve video files, but it is a general file and collaboration platform rather than a video-native one. Mastodon handles short-form social federation beautifully and shares the Fediverse with PeerTube, but it is not a video platform. YouTube remains the default for reach and convenience, at the cost of ownership and policy risk.
PeerTube's distinctive position is "public, federated, video-native, and yours." If your need is private home streaming, Jellyfin is the better tool. If your need is to publish video to a community you control and let it interconnect with the open web without a middleman, PeerTube is the most complete open-source answer available today.
22. Related Articles
If you are building a self-hosted media and communication stack, these pieces from the same series are natural companions:
23. Bottom Line
PeerTube is the most credible open-source challenge to the centralized video platform, not because it replicates YouTube feature for feature, but because it rejects the premise that one company should own publishing, discovery, and audience. You run the server, you choose the rules, your videos sit in storage you control, and federation plus peer-to-peer playback give a small instance a reach that would be impossible for a lone traditional streamer. The price of that sovereignty is operational: you manage the stack, you pay infrastructure rather than attention, you handle moderation, and you must back up your own data. For creators, educators, unions, and communities who have felt the sharp edge of platform dependency, that price is reasonable, and the AGPL license guarantees the escape hatch can never be quietly closed. Self-host PeerTube if you want to own your video presence; rent YouTube if you would rather someone else own it and charge you for the privilege.
Comments (0)
No comments yet. Be the first to comment!