Deploy PeerTube

Deploy and Host PeerTube on Railway

PeerTube is a free, open-source video platform that lets you run your own YouTube-style site on a domain you control. Built by Framasoft under the AGPL-3.0 licence, it stores, transcodes and streams your videos, adds live broadcasting over RTMP, and speaks ActivityPub — so your channels can be followed from Mastodon and other PeerTube sites without anyone signing up on yours. Universities, broadcasters, conferences and creators self-host PeerTube when they want an audience with no advertising algorithm in between.

Deploy PeerTube on Railway and you get the production shape, not a single box: peertube serves the site, API, federation and RTMP ingest; runner does the CPU-heavy transcoding so uploads never slow the site; Postgres holds the catalogue and Redis the job queue; media signs reads from object storage, where the video files live; and mailpit captures outgoing mail. Self-hosting PeerTube this way usually means wiring five machines together — here it is one deploy.

Getting Started with PeerTube on Railway

Set PEERTUBE_ADMIN_EMAIL and PT_INITIAL_ROOT_PASSWORD before deploying — the password is used once, on the boot that installs the instance, to create the root administrator. Open the generated URL and sign in as root. Registration is closed by default, so nobody can claim an account first.

Start at Settings → Configuration to name the instance, write its description and choose whether to open registration. Then click Publish and upload a short video. When the progress bar finishes, open Settings → Runners → Runner jobs: within seconds an HLS job should reach COMPLETED with railway-runner in the Runner column. That screen proves the whole chain — upload, remote transcoding, object storage, signed playback. Play the video back and you are done.

To broadcast live, choose Publish → Go live and paste the RTMP URL and stream key into OBS. The URL already points at the correct public endpoint. Mail lands in the Mailpit inbox on its own URL, behind MP_UI_AUTH.

About Hosting PeerTube

• ActivityPub federation — other instances and Mastodon accounts follow your channels
• HLS adaptive streaming, with optional peer-to-peer assist between viewers of a video
• Live streaming over RTMP, with optional replay saved as a video
• Video Studio: trim, add an intro or outro, mute sections, in the browser
• Channels, playlists, subtitles, chapters, an embeddable player, a REST API
• Moderation: abuse reports, account and instance blocklists, vetted sign-ups

The Railway architecture splits those jobs across services. peertube serves the site and the ActivityPub endpoints. runner claims transcoding jobs over a WebSocket and returns the finished renditions, so a long encode never competes with page requests. Postgres stores the catalogue, accounts and federation state; Redis carries the job queue, cache and live sessions. Object storage holds the video files, and since Railway's buckets are not publicly readable, media signs each read and streams it to the player without exposing the bucket.

Why Deploy PeerTube on Railway

Running PeerTube normally means provisioning a server, database, cache, object storage and reverse proxy by hand.

• One deploy brings up all six services already wired together
• Transcoding runs on its own service, so uploads never slow the site
• Video files go to object storage, so disk size is not your ceiling
• HTTPS, the public domain and the RTMP endpoint are configured for you
• Scale the runner independently as upload volume grows

Common Use Cases

• A university publishing lectures on its own domain, federated so other institutions can follow
• A conference hosting session recordings without handing the archive to a platform that could remove it
• A creator leaving an ad-funded platform but keeping an embeddable player for their own site

Dependencies for PeerTube

• peertube — chocobozzz/peertube:production, wrapped by gridalpha/peertube-railway. Web UI, REST API, ActivityPub, RTMP ingest, live transcoding.
• runner — @peertube/peertube-runner 0.6.0 with ffmpeg. Registers itself at boot, processes VOD and Studio jobs.
• media — a signing service in the same repository, in front of the bucket.
• Postgres 18 — catalogue, accounts, comments, federation state.
• Redis 8 — job queue, cache, live sessions.
• mailpit — axllent/mailpit:latest, a capture-only mail inbox.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/Chocobozzz/PeerTube
• Image: hub.docker.com/r/chocobozzz/peertube
• Docs: docs.joinpeertube.org
• Runtime: Node.js 22, PostgreSQL, Redis, ffmpeg, S3-compatible object storage

Hardware Requirements for Self-Hosting PeerTube

The volume holds only thumbnails, previews, storyboards and upload scratch — videos live in object storage, so it does not grow with your library. Transcoding is the expensive part: encoding runs at roughly real time per rendition, so four resolutions on a one-hour upload cost four hours of runner CPU.

Self-Hosting PeerTube with Docker

Upstream ships a production Compose file. Clone it and edit the env file first:

git clone https://github.com/Chocobozzz/PeerTube.git
cd PeerTube/support/docker/production
cp .env.example .env

Set PEERTUBE_WEBSERVER_HOSTNAME to your domain, PEERTUBE_SECRET to openssl rand -hex 32, and the Postgres credentials. The hostname is baked into every federated identifier, so get it right before the first start.

docker compose up -d
docker compose logs -f peertube

You still need a reverse proxy terminating TLS and, unless video stays on disk, object storage. The Railway template handles both.

Is PeerTube Free to Self-Host?

PeerTube is free software under the AGPL-3.0 licence — no paid tier, no seat count, no enterprise edition. Self-hosting costs only infrastructure: on Railway that is six services, three volumes and object storage billed on what you store and serve. The two costs that grow are runner CPU during transcoding and bandwidth when a video finds an audience.

FAQ

What is PeerTube? PeerTube is an open-source, federated video hosting platform. You run it on your own domain, and other instances or Mastodon accounts can follow your channels over ActivityPub — the closest thing to a self-hosted YouTube.

What does this Railway template deploy? Six services — the PeerTube web app, a transcoding runner, a signing service for object storage, PostgreSQL, Redis and a Mailpit inbox — plus a storage bucket and an RTMP endpoint.

Why does the template include Postgres, Redis and object storage? PeerTube keeps its catalogue, accounts and federation state in PostgreSQL and runs every background job through a Redis queue, so both are required. Object storage is what makes it usable for real video: files go to a bucket, not a fixed-size disk.

How do I log in to PeerTube after deploying? Sign in as root with the value you set for PT_INITIAL_ROOT_PASSWORD. Registration is off by default, so create further accounts from Settings, or open it once moderation is configured.

How do I stream live to self-hosted PeerTube with OBS? Choose Publish → Go live and PeerTube shows an RTMP server URL and a stream key. Paste them into OBS under Settings → Stream as a custom server; the URL already points at the ingest endpoint.

Why is my uploaded video stuck waiting for transcoding? Transcoding is handled by the runner service. Open Settings → Runners → Remote runners and check one is listed with a recent "last contact"; if not, read the runner's logs — it registers itself at boot.

Can I import videos from YouTube into PeerTube? The template ships with HTTP, torrent and channel-synchronisation imports off, which is PeerTube's own default. You can enable them in the configuration, but republish only what you have the right to.