---
title: "Deploy PeerTube"
description: "Video hosting platform you run yourself, with channels and live streams"
category: "CMS"
url: https://railway.com/deploy/peertube-video
---

# Deploy PeerTube

Video hosting platform you run yourself, with channels and live streams

**[Deploy PeerTube on Railway](https://railway.com/template/peertube-video)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/peertube-video/manifest.json

- **Creator:** A3A
- **Category:** CMS

## Template content

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### media https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/peertube.svg

- **Source:** https://github.com/gridalpha/peertube-railway
- **Health check:** /healthz
- **Public domain:** Yes

### runner https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/peertube.svg

- **Source:** https://github.com/gridalpha/peertube-railway
- **Health check:** /healthz

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### peertube https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/peertube.svg

- **Source:** https://github.com/gridalpha/peertube-railway
- **Health check:** /api/v1/config
- **Public domain:** Yes

### mailpit https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mailpit.svg

- **Image:** axllent/mailpit:latest
- **Health check:** /livez
- **Public domain:** Yes

## Buckets

- **peertube-media**

## Documentation

# 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.

![PeerTube web, media gateway and transcoding runner services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1788826261/peertube-architecture.png)

## 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`.

![PeerTube home page listing three published videos with thumbnails](https://res.cloudinary.com/rroe4rtk/image/upload/v1788826263/peertube-browse-videos.png)
![Mandelbrot clip playing in the PeerTube player at 720p](https://res.cloudinary.com/rroe4rtk/image/upload/v1788826265/peertube-watch-video.png)
![Live RTMP broadcast playing with one viewer watching](https://res.cloudinary.com/rroe4rtk/image/upload/v1788826270/peertube-live-stream.png)
![Remote runner jobs table showing completed HLS transcoding](https://res.cloudinary.com/rroe4rtk/image/upload/v1788826273/peertube-runner-jobs.png)

## 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](https://github.com/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

| Variable | Purpose |
|---|---|
| `PT_INITIAL_ROOT_PASSWORD` | Password for the `root` admin |
| `PEERTUBE_ADMIN_EMAIL` | Administrator address, shown on the About page |
| `PEERTUBE_INSTANCE_NAME` | Name shown in the header and to federated peers |
| `PEERTUBE_SIGNUP_ENABLED` | Open registration; `false` by default |
| `PEERTUBE_TRANSCODING_REMOTE_RUNNERS_ENABLED` | Send transcoding to the runner |
| `PEERTUBE_TRANSCODING_720P` and siblings | Extra renditions; each costs storage |
| `PEERTUBE_LIVE_ENABLED` | RTMP live streams |
| `PEERTUBE_USER_VIDEO_QUOTA` | Per-user quota in bytes; `-1` is unlimited |
| `PEERTUBE_SMTP_*` | Point at a real relay before going live |

### Deployment Dependencies

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

## Hardware Requirements for Self-Hosting PeerTube

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU web + 1 vCPU runner | 2 vCPU web + 4 vCPU runner |
| RAM | 1 GB web, 1 GB runner | 2 GB web, 4 GB runner |
| Storage | 5 GB volume + object storage | 5 GB volume + storage sized to your library |
| Runtime | Node.js 22, ffmpeg 4.3+ | Node.js 22, ffmpeg 5+ |

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.


## Similar templates

- [Libredesk - Complete Setup](https://railway.com/deploy/libredesk-complete-setup) — Complete self-hosted omnichannel customer support desk.
- [Paperless-ngx](https://railway.com/deploy/paperless-ngx-3) — Paperless-ngx — document management with OCR and full-text search
- [Instatic CMS - Postgres](https://railway.com/deploy/instatic-cms-postgres) — Design, build and manage powerful static sites from state-of-the-art CMS

Open this page in a browser: https://railway.com/deploy/peertube-video