RelayrtcDocs
Get started
Documentation
Self-hosting

Operate a self-hosted installation

Manage your generated RelayRTC folder, public addresses and persistent data.

On this page

These procedures apply to the browser setup wizard. Run Compose commands inside the generated relayrtc folder. Rooms and streaming share one project.

Configuration and data

Path in your installation folderPurpose
.envSettings and generated credentials
docker-compose.ymlComplete stack with pinned service images
wizard.jsonWizard version and nonsecret settings
runtime/monitoringPrometheus configuration and scoped credentials
runtime/streamingGateway configuration and certs/
backupsConfiguration snapshots made when the wizard saves changes

PostgreSQL, retained streaming objects, Grafana, Prometheus and TURN accounting use separate Docker volumes. Save the configuration folder as well as those volumes. Configuration snapshots are not database or media backups.

Gateway and Prometheus receive only the runtime subdirectories they need. Keep .env, the Compose file and configuration backups private. The wizard preserves configured infrastructure secrets when you reopen the same installation at the same version.

The installer creates its child folder using the owner of the mounted parent directory on Linux. It does not change the parent directory's permissions. Keep the installation on a local filesystem supported by Docker Desktop or Docker Engine and restrict access to your account and Docker.

Change settings

Edit .env for service settings consumed by the generated Compose file, then apply them during a maintenance window:

Shell
docker compose up -d --remove-orphans

Existing secrets must remain unchanged unless you perform a coordinated rotation. Editing a database or storage password does not update an already initialized account. Keep signing and encryption keys with backups.

You can reopen the wizard at its installed version by running the installation command from the parent folder with relayrtc/relayrtc:0.1.4. It reads relayrtc/wizard.json, offers Keep current credentials for configured providers, and preserves infrastructure secrets. A different installer version is rejected rather than silently rewriting an existing deployment.

The wizard writes configuration but does not recreate running services. Apply the saved configuration through Compose. Recreating API, signaling, media or workers interrupts active sessions.

Local endpoints

ServiceDefault
Consolehttp://localhost:3002
REST APIhttp://localhost:8080/v1
Signalingws://localhost:8081/v1/connect
Media readinesshttp://localhost:8083/ready
PostgreSQL host accesslocalhost:5433
STUN/TURN3478 TCP/UDP
Grafanahttp://localhost:3000
Prometheushttp://localhost:9090
RTMP ingest1935 TCP
WHIP media8189 UDP

Grafana uses GRAFANA_ADMIN_USER, defaulting to admin, and the generated GRAFANA_ADMIN_PASSWORD in your private .env. Your RelayRTC account is created separately in the console.

Start, inspect or stop

Shell
docker compose up -d --remove-orphans
docker compose ps -a
docker compose logs --tail=100 api console migrate

After ending calls and draining streaming, stop the stack:

Shell
docker compose down

This retains data volumes. Do not add --volumes when preserving an installation. Existing restart policies apply after Docker restarts. Keep the generated folder available for its runtime bind mounts.

Public hosting and ports

Public setup requires:

  • DNS for the console, API and signaling addresses entered in the wizard.
  • Trusted HTTPS for console/API and WSS for signaling.
  • A reverse proxy forwarding signaling WebSocket upgrades at /v1/connect. With one hostname, route /v1/connect to signaling, other /v1/ requests to the API, and remaining requests to the console.
  • Reachable mediasoup announced addresses and coturn public IP.
  • The application's exact origin in RELAYRTC_SIGNALING_ALLOWED_ORIGINS.
  • Public streaming addresses from streaming access.

Resend and OAuth remain optional on a public server. If you skip email, verification and email-dependent recovery/invitations remain unavailable. Configure a sender later to enable them.

The generated API, console, signaling, database and monitoring bindings are loopback-only. A reverse proxy on the same host can reach those bindings. A containerized proxy needs an explicitly configured shared network. The installer does not provision a proxy or TLS certificates.

Open the mediasoup TCP/UDP range, default 40000-40003, coturn 3478 TCP/UDP and relay range 49160-49200 UDP. Remote ingest also needs 1935 TCP and 8189 UDP. Configure trusted certificates before using TURN TLS or RTMPS. Gateway RTMPS files belong in runtime/streaming/certs.

Backups

Drain traffic and stop application/worker writes before taking a coordinated backup of:

  1. PostgreSQL and its migration/release information.
  2. The complete generated relayrtc folder with original keys.
  3. Retained streaming objects from the storage volume.
  4. Proxy and trusted TLS configuration.

For the default project, create a database dump without binary shell redirection:

Shell
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc -f /tmp/relayrtc.dump'
docker compose cp postgres:/tmp/relayrtc.dump ./relayrtc.dump

Wait for each command to succeed and move the dump to protected backup storage. Use your Docker volume backup procedure for retained objects and other stateful volumes.

Upgrade

Read the target release's migration instructions before changing pinned service versions. Back up and drain the deployment first. Keep the installed wizard version for ordinary configuration changes. Pulling a newer latest installer does not automatically upgrade an existing folder.

Do not point a freshly generated configuration at existing volumes. A target release must preserve original credentials and explicitly account for database/schema changes before recreating services. The wizard currently handles initial installation and same-version settings, not automatic cross-version migration.

Restore and rollback

Restore the database, retained objects and original configuration as one compatible set with workers stopped. An older image cannot undo applied migrations. Use a matching backup when a release cannot read the restored schema.

The default project name is relayrtc, with a fixed media subnet. A second folder is not an isolated second deployment on the same Docker engine. Multiple simultaneous installations require explicit project, network and port changes.

Existing installations

The folder wizard does not automatically adopt an older named-volume setup or source deployment. It refuses fresh configuration when a relayrtc project already has containers or volumes. Keep the original .env, deployment definition, keys and data, and perform a controlled migration rather than generating replacement secrets.

Source developers can continue using pnpm docker:up and the canonical source Compose definitions.