Workload · Running a PeerTube instance

PeerTube self hosted: a video platform on a server you control

To run PeerTube self hosted you need a Linux server with Node.js, PostgreSQL, Redis, FFmpeg and nginx, a domain you will never change, and enough disk and upload capacity for your videos. The project's figures start at one core and 1.5 GB of memory, but transcoding decides the machine: the docs suggest 8 cores and 8 GB when it runs on the same box.

The short version
  1. Official minimum: 1 core, 1.5 GB RAM, 20 Mbit/s upload
  2. Transcoding on the same box: 8 cores, 8 GB RAM
  3. The domain is fixed at first start, so pick it carefully
  4. Sign-ups are off by default; follower approval is not

What a PeerTube instance asks of the machine

Most of PeerTube is light; the heavy part is FFmpeg turning every upload into the resolutions viewers stream. The project publishes three reference points:

InstanceCPUMemoryUpload
Minimum1 core1.5 GB20 Mbit/s
Large, about 1,000 viewers at once4 cores4 GB1 Gbit/s
Transcoding on the same machine8 cores8 GBas above

Storage has two sides, the docs say: the space the library takes, and how fast the disks can read it. Keeping both HLS and the older web-video format roughly doubles each video; the production example enables HLS only. For a very large library the docs point to object storage.

Bandwidth is division. A 1 Gbit/s uplink serving 5 Mbit/s streams tops out near 200 simultaneous viewers, if disk reads keep up. Instances that follow yours can mirror popular videos and carry part of that load.

Why a whole server suits a video platform

A video platform fails in two predictable ways: transcoding starves everything else of CPU, and a popular video turns into a bandwidth bill. On a dedicated server every core, all the memory and all the disks are yours, so nobody else's encode slows yours.

  • The port is unmetered. No transfer allowance and no overage line, so the month a video gets shared is billed like any other. The included port is 500 Mbps or 1 Gbps depending on the line, and can be raised for a fixed monthly amount.
  • Root access, so you install the Node.js, PostgreSQL and FFmpeg releases the PeerTube docs ask for.
  • An out-of-band console on rack servers, blades and the m510 and m710x cartridges: the screen and the power button, even if a firewall rule locks you out.
  • Reinstall from the control panel as often as you like, with no ticket to open.
  • Month to month, no contract: start small, move up when the audience arrives.

The server that fits your instance

Match the class to the job, then pick the build on the order page.

  • A small community instance with modest uploads fits one of the compact single-processor cartridges, which suit one job.
  • An instance that transcodes its own uploads belongs on a two-processor server: the docs recommend 8 cores and 8 GB for transcoding on the same machine, and more cores finish the queue sooner.
  • A large library needs disks before cores. Our storage servers take hardware RAID and many drive bays, and a build to order can carry up to 24 bays.
  • A busy public instance may need more port than the one included. The streaming servers page explains the faster ports.

A racked server is handed over within 30 minutes of payment approval. A build to order with extra disks takes longer; that page says which lead time applies.

Up and running in an evening

The official guide installs PeerTube as its own user under /var/www/peertube, behind nginx. Point your domain's DNS at the server first; the certificate step needs it.

  1. Install the dependencies: curl and unzip, Python 3.8 or newer with pip, Node.js 22 (from NodeSource), pnpm, PostgreSQL 14 or newer, Redis 6.2 or newer and FFmpeg 4.3 or newer. On Debian or Ubuntu the main line is sudo apt install certbot nginx ffmpeg postgresql postgresql-contrib openssl g++ make redis-server git cron wget, then sudo systemctl start redis postgresql.
  2. Create the user with sudo useradd -m -d /var/www/peertube -s /usr/sbin/nologin peertube, then sudo chmod 755 /var/www/peertube so nginx can reach the files; Ubuntu 24.04 creates new home folders private.
  3. Create the database user on its own line, because it prompts for the password (which keeps it out of your shell history): sudo -u postgres createuser -P peertube. Then create the database and its extensions:
sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod

Then fetch the latest release and its Node modules. The block is chained with &&, so it stops at the first step that fails:

cd /var/www/peertube && VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && test -n "$VERSION" && echo "Latest Peertube version is $VERSION" && sudo -u peertube mkdir config storage versions && sudo -u peertube chmod 750 config/ && cd /var/www/peertube/versions && sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && sudo -u peertube unzip -q peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip && cd /var/www/peertube && sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest && cd ./peertube-latest && sudo -H -u peertube npm run install-node-dependencies -- --production
  1. Copy peertube-latest/config/default.yaml to config/default.yaml and production.yaml.example to config/production.yaml. Never edit default.yaml.
  2. In production.yaml, set the webserver hostname, a secret made with openssl rand -hex 32, the database password, and admin.email; add smtp if the instance should send email.
  3. Copy the official nginx file from peertube-latest/support/nginx/peertube into /etc/nginx/sites-available/, replace its host placeholders as the guide shows, link it into sites-enabled and get a certificate with Certbot.
  4. Copy the bundled unit support/systemd/peertube.service into /etc/systemd/system/ and reload systemd with sudo systemctl daemon-reload. To have it come back after a reboot, run sudo systemctl enable peertube; to start it now, sudo systemctl start peertube. Watch the log with sudo journalctl -feu peertube.

Prefer Docker? The project ships a Compose file. In an empty folder, download its docker-compose.yml and .env, fill in the database credentials, domain, email and secret in .env, put the official nginx template in docker-volume/nginx/peertube and issue the first certificate with the Certbot container, both as the Docker guide shows, then run docker compose up. New to containers? See our Docker Compose walkthrough.

The domain becomes permanent at first start: PeerTube does not support changing its web host later. Choose the hostname you mean to keep before you launch.

Close the open doors on day one

A fresh instance creates a root administrator whose generated password is written to the logs. Change it at once with npm run reset-password -- -u root (as the peertube user, from peertube-latest, with the config folder set as the guide shows), or under Docker with docker compose exec -u peertube peertube npm run reset-password -- -u root.

  • Sign-ups: the production example ships with signup disabled and approval required. Keep it so until you have moderators; open registration invites spam uploads.
  • Followers: other instances may follow yours without approval by default. Tick "Manually approve new platform followers" under Administration, Settings, Configuration, Basic.
  • Mirroring: remote_redundancy.videos.accept_from decides who may copy your videos: nobody, followings or anybody.
  • Firewall: allow SSH first, then ports 80 and 443, and 1935 only if you switch on live streaming (RTMP). Make sure the rules cover IPv6 as well.

Transcoding and federation choices

The production example transcodes with one thread, one job at a time. Raise threads and concurrency to match your cores and keep only the resolutions you need.

If encoding outgrows the web server, PeerTube can hand it to remote runners: separate machines that take transcoding and other heavy jobs and post the results back. Register only runners whose administrators you trust, because a runner can alter video content.

Federation is your choice of neighbours: following an instance shows its videos on yours, and being followed shows yours on theirs.

Backups and upgrades without surprises

Before every upgrade, read the IMPORTANT NOTES in the changelog and take a database dump with the command from the official guide:

SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
    cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
    sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null

Check the file exists and is not empty. Then run cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh. With git installed it leaves a production.yaml.new with the differences marked; review it before replacing your config, then restart PeerTube. Rolling back means pointing peertube-latest at the previous version and restoring that dump.

The dump holds the database only. Copy /var/www/peertube/storage and /var/www/peertube/config somewhere off the server too, because the videos and your secrets are not in it.

When this is the wrong place for it

You run PeerTube yourself: we keep the hardware and the network up, but installing, moderating and upgrading the instance is your job. If you only want to publish your own channel, without federation or moderation, a hosted video streaming plan is less work. Moving an existing instance? Our migration guide covers the cutover.

Questions people ask

How much memory does a small PeerTube instance really need?
The project's minimum is 1.5 GB of RAM and one core. That covers serving videos, not encoding them quickly; for transcoding on the same machine the docs suggest 8 GB and 8 cores.
Should I install from the production guide or with Docker?
Both are official. The production guide sets up each piece as a normal system service, easier to tune and back up. Docker puts PeerTube, PostgreSQL, Redis, nginx and certificate renewal in one Compose file and starts quicker.
Can I move my instance to a new domain later?
No. PeerTube does not support changing the web host after first start, since federated instances know your videos and accounts by that address. When you change servers, keep the domain and repoint its DNS.
Do I have to federate with other instances?
No. You can refuse followers, approve each one by hand, and limit who may mirror your videos.
Can PeerTube stream live, and what does that need?
Yes, once you enable live, which is off in the production example. Encoders push RTMP to port 1935, so open that port; the stream is transcoded like an upload, adding CPU load while you are on air.
What happens to my bill if one of my videos goes viral?
On our dedicated servers, nothing: the port is unmetered, with no allowance and no overage line. What can run out is the port's speed, and then a faster port or mirroring followers help.

Get a server for your PeerTube instance

Pick a machine with the cores for transcoding and the disks for your library, on a port nobody meters, month to month.

Choose your server

Read next