RelayrtcDocs
Get started
Documentation
Self-hosting

Operate self-hosted streaming

Configure remote streaming access, understand worker capacity and maintain retained media.

On this page

Use this page after installing RelayRTC, which includes streaming. Run Compose from your generated relayrtc folder. There is no separate streaming setup.

Configure public access

SettingRequired meaning
STREAMING_PUBLIC_ORIGINBrowser-facing API origin, including the published port; use HTTPS remotely
STREAMING_PUBLIC_RTMP_ORIGINEncoder-facing RTMP or RTMPS origin
STREAMING_GUEST_SIGNALING_URLBrowser-facing signaling WebSocket URL including /v1/connect
STREAMING_ALLOWED_ORIGINSExact console/application origins permitted to view media
STREAMING_INGEST_BINDHost interface for encoder/WHIP connectivity; loopback is the local default
STREAMING_WEBRTC_HOSTSReachable addresses announced by the WHIP gateway
STREAMING_SOURCE_ALLOWED_HOSTSExact public hosts for every upstream HLS manifest, segment and redirect; empty disables pulls

Preparation derives empty local API/signaling origins from the selected host ports. Those defaults do not configure public TLS. Review them explicitly for a remote installation, including after changing a port.

Private gateway, worker and S3 addresses remain internal Docker addresses. Do not replace them with the public API hostname or expose the storage bucket.

RTMP uses port 1935 TCP. RTMPS uses 1936 TCP when enabled with a trusted certificate. WHIP uses the authorized API HTTP path plus gateway media on 8189 UDP. A remote encoder needs those routes and firewall rules; HTTP connectivity alone does not establish WebRTC media. RTC guest stages additionally use the base media/TURN paths.

For RTMPS, put the trusted certificate/key at the configured gateway certificate mount and set STREAMING_RTMP_ENCRYPTION to the desired supported mode. Changing an origin to rtmps:// does not enable encryption by itself.

Services

RoleImage or service
Source encoding and compositionstreaming-worker, using the streaming image
HLS attachments and external destinationsstreaming-outputs, same image with output-server command
Probes and upstream pullsstreaming-sources, same image with restream-server command
Recordings, clips and buffersstreaming-recordings, same image with recording-server command
Object storage and setupstreaming-storage and streaming-storage-init images
Encoder admission and canonical mediaPinned MediaMTX gateway

Use docker compose ps -a, docker compose logs, docker compose up -d and docker compose down from the installation folder. The generated manifest pins matching images while preserving worker commands and resource limits. From a full matching source checkout, pnpm docker:up builds and starts the complete stack; it requires host Node/pnpm. pnpm docker:status, pnpm docker:logs and pnpm docker:down cover the same services.

Capacity and private delivery

The canonical worker defaults to four source slots. The output worker defaults to four output slots; HLS itself occupies one. Input normalization, composition, external transcoding and recording finalization consume different resources. Increasing admission quotas does not provision more workers or CPU.

The supplied topology uses a fixed RTP receiver address and per-job port ranges. Do not scale that container with duplicate static addresses. Additional worker hosts require an explicit network/receiver design. Keep FFmpeg guards, resource limits and private API/gateway/storage access in place.

Live playback, DVR and VOD must pass through the authorized API origin. Preserve token queries, private/no-store response headers, streaming responses and suitable proxy timeouts. Keep gateway HLS/RTSP/API ports, worker health/metrics and storage ports private. Shared CDN caching and public buckets bypass this delivery model and are not configured by the supplied stack.

The streaming monitoring configuration scrapes private endpoints with prepared credentials. Watch source/output readiness, queue age, expired leases, recording cleanup, buffer pressure, guest cleanup and usage coverage. Use resource IDs and safe error codes rather than logging grants or upstream URLs.

Upgrades and draining

Before recreating services, prevent new event/room commands in your application. Cancel pending schedules, stop upstream registry jobs and broadcasts, finalize recordings, stop sources and wait for pending operations and retained-window cleanup as appropriate. Preserve access needed for bounded cleanup.

STREAMING_BROADCASTS_ENABLED=false blocks new broadcast admission and drains runs while source cleanup remains active. Feature controls for guests, DVR and mixers have their own draining semantics. Keep streaming control services running while broadcasts, recordings and retained-data cleanup drain. The standard stack keeps streaming enabled.

Take coordinated backups and follow the target release's upgrade procedure. The wizard supports initial configuration and same-version changes. Do not generate fresh keys for existing metadata or object storage.

Run commands sequentially and leave application services stopped if migration fails. Keep the database and object storage schemas compatible with the chosen release; removing tables while active cleanup depends on them is unsupported. Recheck media and asset access after the upgrade before admitting new events.

Backups and restore

Drain work and quiesce API/worker writes before creating coordinated database/storage backups. Use the PostgreSQL backup procedure, and save .env, Compose overrides, TLS material and original encryption/signing keys privately.

For the supplied local storage volume, stop storage after application/worker writes have stopped. A Bash example copies that stopped container's data read-only:

Shell
docker stop relayrtc-streaming-storage-1
docker run --rm --volumes-from relayrtc-streaming-storage-1:ro --mount "type=bind,source=$PWD,target=/backup" alpine:3.22 tar -C /data -czf /backup/streaming-storage.tar.gz .

Use the actual storage container name for a customized project, a unique protected backup destination and the appropriate bind-path syntax for your host shell. For external object storage, use the provider's consistent backup/snapshot procedure instead. Do not expose administrator credentials in command history or backups shared with support.

Restore database, objects and keys as one compatible set on an isolated installation. Keep source/output/recording workers and the ingest gateway stopped while control services reconcile stale leases. Admit publishers and resume jobs deliberately; do not restore a running worker snapshot. Test grant revocation, retained asset playback and cleanup before returning traffic.

Troubleshooting

SymptomCheck
Missing image or attempted buildPinned Docker Hub service tags and public image visibility. Installer deployments use prebuilt images
Encoder connects but video is unavailablereadiness, source production, worker capacity and private gateway access
WHIP fails remotelyExact browser origin, SDP limits, announced gateway address and UDP 8189
Asset never becomes readyRecording-worker capacity, storage health, safe lastError and partial-output policy
HLS pull rejectedEvery allowed hostname/redirect, public DNS, TLS and supported input profile
DVR stallsActual retained range, pins, byte pressure and shared capture capacity
Scene remains pendingRequired inputs, saved versions and observed activation operation

For access and lifecycle details, use the feature guides rather than modifying database state or manually completing operations.