Docker Pulls Docker Tag

A Docker container for running PeerTube Runner with GPU acceleration for video transcoding and transcription tasks.

docker run -d --name peertube-runner-gpu \
 --gpus all --restart unless-stopped \
 -e PEERTUBE_RUNNER_URL=https://your-peertube-instance.com \
 -e PEERTUBE_RUNNER_TOKEN=your_token_here \
 -e NVIDIA_DRIVER_CAPABILITIES=compute,video,utility \
 bvdcode/peertube-runner-gpu:latest

Key Features:

• ✅ Smart NVENC Encoding: Automatically uses GPU encoding when available, falls back to CPU if needed
• ✅ Reliable Registration: Fixed registration logic that accurately reports success/failure
• ✅ GPU Transcription: Whisper models run on GPU via CTranslate2
• ✅ Model Auto-Download: Whisper models download automatically on first use
• ✅ Persistent Cache: Mount /home/runner/.cache/ to preserve downloaded models across restarts

This project provides a containerized PeerTube Runner with NVIDIA CUDA support, designed for hardware-accelerated video processing including transcoding and transcription using Whisper and CTranslate2. The container supports all major PeerTube job types and is optimized for efficient processing in a PeerTube environment.

• 🚀 GPU Acceleration: NVIDIA CUDA 12.8.0 support with cuDNN runtime
• � Video Transcoding: Support for VOD web video, HLS, audio merge transcoding
• 📺 Live Streaming: Live RTMP to HLS transcoding support
• 🎬 Video Studio: Video studio transcoding capabilities
• 🎵 Video Transcription: AI-powered transcription using Whisper-CTranslate2
• 🐳 Docker Ready: Easy deployment with Docker and Docker Compose
• 🔧 Flexible Configuration: Environment variables or config file support
• ⚙️ Auto-building: GitHub Actions for automated Docker image builds
• 🏃 Production Ready: Based on Ubuntu 22.04 with optimized dependencies

• vod-web-video-transcoding - Video-on-demand web video transcoding
• vod-hls-transcoding - HLS video transcoding
• vod-audio-merge-transcoding - Audio merge transcoding
• live-rtmp-hls-transcoding - Live streaming transcoding
• video-studio-transcoding - Video studio editing transcoding
• video-transcription - AI-powered video transcription
• generate-video-storyboard - Video storyboard generation

• Docker and Docker Compose installed
• NVIDIA GPU with CUDA support (optional, container can run without GPU)
• NVIDIA Container Toolkit for GPU acceleration

For Ubuntu/Debian:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
 sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
 sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Using Docker Compose (Recommended):

git clone https://github.com/bvdcode/peertube-runner.git
cd peertube-runner
# Edit docker-compose.yml with your URL and token
docker-compose up -d

Using Docker Run:

docker run -d --name peertube-runner-gpu --gpus all --restart unless-stopped \
 -e PEERTUBE_RUNNER_URL=https://your-instance.com \
 -e PEERTUBE_RUNNER_TOKEN=your_token \
 bvdcode/peertube-runner-gpu:latest

With Config File:

Mount your config.toml to /home/runner/config.toml:ro in volumes.

Alternatively, you can use a config.toml file:

[jobs]
concurrency = 2
[ffmpeg]
threads = 4
nice = 20
[transcription]
engine = "whisper-ctranslate2"
model = "large-v3"
[[registeredInstances]]
url = "https://your-peertube-instance.com"
runnerToken = "your_runner_token_here"
runnerName = "my-custom-runner"

• tiny - Fastest, least accurate (39 MB)
• base - Good speed/accuracy balance (74 MB)
• small - Better accuracy (244 MB)
• medium - High accuracy (769 MB)
• large-v2 - Very high accuracy (1550 MB)
• large-v3 - Best accuracy (1550 MB, default)

You can limit the runner to specific job types by setting PEERTUBE_RUNNER_JOB_TYPES:

# Only transcription jobs
PEERTUBE_RUNNER_JOB_TYPES=video-transcription
# Multiple job types
PEERTUBE_RUNNER_JOB_TYPES=vod-hls-transcoding,video-transcription,video-studio-transcoding,generate-video-storyboard
# All jobs (default if not specified)
# Leave empty or omit the variable

Control how the runner behaves when a runner with the same name already exists on the PeerTube instance:

Exits with an error message and instructions when a name conflict occurs:

PEERTUBE_RUNNER_NAME_CONFLICT=exit

Use case: Strict environments where you want to manually manage runner names.

Automatically generates unique names by appending a timestamp:

PEERTUBE_RUNNER_NAME_CONFLICT=auto

Example: peertube-runner-gpu → peertube-runner-gpu-1753501234

Use case: Development or testing environments where you want hassle-free deployment.

Waits for the existing runner to be removed, checking every 30 seconds:

PEERTUBE_RUNNER_NAME_CONFLICT=wait

Use case: When replacing an existing runner and you want to wait for manual cleanup.

• bvdcode/peertube-runner-gpu:latest - Latest stable version
• ghcr.io/bvdcode/peertube-runner-gpu:latest - GitHub Container Registry

The project uses GitHub Actions for automated builds:

• Builds trigger on pushes to main branch
• Images are published to both Docker Hub and GitHub Container Registry
• Manual builds can be triggered via workflow dispatch

• Base Image: NVIDIA CUDA 12.8.0 with cuDNN runtime on Ubuntu 22.04
• Python: Python 3 with pip
• Node.js: Node.js 20.x LTS
• FFmpeg: For video processing and transcoding
• PeerTube Runner: Latest version from npm

• CTranslate2 4.6.0: Optimized inference library for Transformer models
• Whisper-CTranslate2 0.5.3: Fast implementation of OpenAI's Whisper speech recognition

• Non-root user execution for security
• Automatic configuration generation from environment variables
• Flexible job type selection
• GPU resource reservation with Docker Compose
• Persistent configuration via volume mounts

To build the Docker image locally:

git clone https://github.com/bvdcode/peertube-runner.git
cd peertube-runner
docker build -t peertube-runner-gpu .

The Dockerfile supports standard Docker build arguments and will automatically install all dependencies.

When the container starts, it will:

1. Configuration Setup: Check for existing config file or generate from environment variables
2. PeerTube Connection: Connect to your PeerTube instance using provided URL and token
3. Runner Registration: Register as a runner with specified capabilities
4. Job Processing: Accept and process jobs based on configured job types:
   • Video transcoding jobs use FFmpeg with GPU encoding when available
   • Transcription jobs use Whisper with GPU acceleration
   • All jobs respect concurrency limits
5. Smart Encoding: Automatically uses NVENC GPU encoding, falls back to CPU if GPU unavailable
6. Non-root Execution: Runs as runner user for security Transcription Only (GPU):

environment:
 - PEERTUBE_RUNNER_JOB_TYPES=video-transcription
 - PEERTUBE_RUNNER_WHISPER_MODEL=medium

High-Performance Transcoding:

environment:
 - PEERTUBE_RUNNER_CONCURRENCY=4
 - PEERTUBE_RUNNER_FFMPEG_THREADS=8

CPU-Only (No GPU):

environment:
 - PEERTUBE_RUNNER_ENGINE=whisper-ffmpeg
 - PEERTUBE_RUNNER_WHISPER_MODEL=base
# Remove deploy.resources section

Auto-Generated Names (Dev/Testing):

environment:
 - PEERTUBE_RUNNER_NAME_CONFLICT=auto # Adds timestamp if name exists
 devices:
 - capabilities: [gpu]

# Real-time logs
docker-compose logs -f peertube-runner-gpu
# Last 100 lines
docker-compose logs --tail 100 peertube-runner-gpu

# Check container status
docker-compose ps
# Check resource usage
docker stats peertube-runner-gpu

# Check GPU usage inside container
docker exec peertube-runner-gpu nvidia-smi
# Monitor GPU usage in real-time
watch -n 1 'docker exec peertube-runner-gpu nvidia-smi'

Error: CUDA driver version is insufficient or nvidia-smi not found

Solution:

1. Verify NVIDIA drivers are installed:

nvidia-smi

2. Check Docker can access GPU:

docker run --rm --gpus all nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

3. Ensure nvidia-container-toolkit is installed and Docker is restarted.

Error: PEERTUBE_RUNNER_URL and PEERTUBE_RUNNER_TOKEN environment variables are required

Solution:

• Verify environment variables are set in docker-compose.yml
• Check that config.toml file exists if using file-based configuration
• Ensure proper escaping of special characters in tokens

Error: Failed to connect to PeerTube instance

Solution:

• Verify PeerTube instance URL is accessible from the container
• Check firewall rules and network connectivity
• Ensure runner token is valid and not expired
• Test connection: curl -I https://your-peertube-instance.com

Error: Jobs not being picked up or failing

Solution:

• Check PeerTube instance runner configuration
• Verify job types are properly configured
• Monitor logs for specific error messages
• Ensure sufficient disk space and memory

GPU Not Detected:

• Check: nvidia-smi on host
• Verify: docker run --rm --gpus all nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi
• Install nvidia-container-toolkit if missing

"NVENC not available" in logs:

• Container works fine without GPU, just uses CPU en

• Check URL is accessible: curl -I https://your-instance.com

• Verify token format: ptrrt-... (registration token, not runner token)

• Name conflict? Use PEERTUBE_RUNNER_NAME_CONFLICT=auto

Performance Tuning:

• PEERTUBE_RUNNER_WHISPER_MODEL=small
• PEERTUBE_RUNNER_CONCURRENCY=1

• PEERTUBE_RUNNER_CONCURRENCY=6
• PEERTUBE_RUNNER_FFMPEG_THREADS=12

A: Run docker-compose pull followed by docker-compose up -d.

• Issues: GitHub Issues
• PeerTube Documentation: Official Docs
• Docker Hub: bvdcode/peertube-runner-gpu

This project is open source. Please check the license file for details.

• PeerTube - Federated video hosting network
• PeerTube Runner - Official PeerTube runner package
• Whisper-CTranslate2 - Fast Whisper implementation
• CTranslate2 - Optimized inference library
• NVIDIA Container Toolkit - GPU support for containers

• PeerTube team for the excellent video platform and runner system
• OpenAI for Whisper speech recognition model
• NVIDIA for CUDA toolkit and container support
• Contributors and users of this project

Built with ❤️ for the PeerTube community

For more information about PeerTube runners, visit the official documentation. FAQ

Q: Does it work without GPU? A: Yes! Auto-detects and falls back to CPU. Remove deploy.resources section for CPU-only.

Q: Which Whisper model? A: Quality: large-v3 > large-v2 > medium > small > base > tiny. Use small/base for CPU.

Q: Multiple runners on one machine? A: Yes, use different container/runner names for each.

Q: Runner name already exists? A: Set PEERTUBE_RUNNER_NAME_CONFLICT=auto to auto-generate unique names with timestamp.

Q: How to update? A: docker-compose pull && docker-compose up -d