Skip to content
Klutch.sh Docs

Deploying a PeerTube App

Introduction

PeerTube is an open-source, federated video hosting platform. Deploying PeerTube with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for videos, configs, and logs—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your PeerTube Dockerfile (GitHub is the only supported git source)
  • PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000; connect on 5432)
  • Redis instance (deploy as a Klutch.sh TCP app on port 8000; connect on 6379)
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • PeerTube serves HTTP on internal port 9000; choose HTTP traffic and set the internal port to 9000.
  • Persistent storage is required for videos, thumbnails, logs, and configuration.

Repository layout

peertube/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t peertube-local .
docker run -p 9000:9000 peertube-local

Dockerfile for PeerTube (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM chocobozzz/peertube:latest


ENV LISTEN_PORT=9000


EXPOSE 9000
CMD ["npm", "start", "--", "--listen", "0.0.0.0:9000"]

Notes:

  • Pin the image tag (e.g., chocobozzz/peertube:v6.x) for stability; update intentionally.
  • Adjust command/ENV if you maintain a custom fork.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • LISTEN_PORT=9000
  • PEERTUBE_WEBSERVER_HOSTNAME=example-app.klutch.sh
  • PEERTUBE_DB_USERNAME=<db-user>
  • PEERTUBE_DB_PASSWORD=<db-password>
  • PEERTUBE_DB_HOSTNAME=<db-host>
  • PEERTUBE_DB_PORT=5432
  • PEERTUBE_DB_SUFFIX=<db-name>
  • PEERTUBE_REDIS_HOSTNAME=<redis-host>
  • PEERTUBE_REDIS_PORT=6379
  • PEERTUBE_SECRET=<secure-random>
  • Optional email: PEERTUBE_SMTP_HOSTNAME, PEERTUBE_SMTP_USERNAME, PEERTUBE_SMTP_PASSWORD, PEERTUBE_SMTP_PORT, PEERTUBE_SMTP_FROM

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=npm start -- --listen 0.0.0.0:9000
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /data/peertube/storage — videos, thumbnails, and assets.
  • /data/peertube/config — configuration.
  • /data/peertube/logs — logs.

Ensure these paths are writable inside the container.

Deploy PeerTube on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 9000.
  4. Add the environment variables above, including DB/Redis credentials, hostname, and secrets.
  5. Attach persistent volumes for /data/peertube/storage, /data/peertube/config, and /data/peertube/logs sized for your video library and logs.
  6. Deploy. Your PeerTube instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

List videos:

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v1/videos"

Upload a video (replace token with an access token):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v1/videos/upload" \
  -H "Authorization: Bearer <token>" \
  -F "video=@/path/to/video.mp4" \
  -F "name=Hello from PeerTube on Klutch.sh"

Health checks and production tips

  • Add an HTTP probe to / or /api/v1/videos for readiness.
  • Enforce HTTPS at the edge; forward internally to port 9000.
  • Keep secrets, DB, and Redis credentials in Klutch.sh secrets; rotate them regularly.
  • Monitor storage usage on /data/peertube/storage; resize before it fills.
  • Pin image versions and test upgrades in staging; back up DB and storage before updates.

PeerTube on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 9000 configured, and Postgres/Redis connected, you can deliver federated video hosting without extra YAML or workflow overhead.