Install with Docker Compose

This method uses prebuilt images to run SyncTV, PostgreSQL, and Redis on one server, NAS, or virtual machine. Kubernetes environments use the Helm deployment.

If you have not chosen a deployment model yet, start with Choose a Deployment Path.

Prerequisites

• Docker Engine and Docker Compose v2.
• A durable working directory for the Compose configuration, environment files, and volumes.
• A password manager for the generated root password and long-lived secrets.

Generate Environment Files

Generate your Compose environment

Choose the values you want to control. Database credentials and application secrets are generated in page memory and included in the downloaded files.

Deployment settings

Initial root username Initial root password

Show Generate

This account is created on the first startup when the database is empty.

Download .env.synctv .env.postgres .env.redis

Download files

Files are ready to download.

Download all files

Download .env.synctv Download .env.postgres Download .env.redis

Save the three files in the same directory as docker-compose.yml, then run docker compose up -d.

Warning: this file contains passwords and long-lived secrets. Do not share it, commit it to a repository, or upload it to a third-party service.

The generator downloads three files:

• .env.synctv: SyncTV database connection, authentication keys, and root bootstrap settings.
• .env.postgres: PostgreSQL user, password, and database name.
• .env.redis: Redis AUTH password.

Random secrets are generated in page memory and never written to browser storage or the server. Keep the downloaded files together and back them up.

Install

1. Create a working directory and download the production Compose configuration:

   mkdir -p synctv && cd synctv
   curl -fsSL https://raw.githubusercontent.com/synctv-org/synctv/next/docker-compose.yml -o docker-compose.yml

2. Return to Generate Environment Files, download the three environment files, and put them in the current directory.

3. Validate the final Compose configuration:

   docker compose -f docker-compose.yml config --quiet

4. Pull the images and start the services in the background:

   docker compose -f docker-compose.yml up -d

Compose uses synctvorg/synctv:latest. Release tags are updated by maintainers in the Compose file.

Verify

Inspect the containers and request the readiness endpoint from inside the SyncTV container:

docker compose -f docker-compose.yml ps
docker compose -f docker-compose.yml exec synctv \
  curl -fsS http://localhost:8081/health/ready

The HTTP API is available at http://localhost:8080. On the first startup with an empty database, the root username and password come from .env.synctv.

Environment Files and Versions

Docker Compose loads the required .env.postgres, .env.redis, and .env.synctv files through env_file: PostgreSQL reads database variables, Redis reads REDIS_PASSWORD, and SyncTV reads SYNCTV_* application settings. The Compose file also fixes SYNCTV_DATA_DIR to /data so runtime data stays on the named volume. Reuse the same files across restarts, new shells, host reboots, and upgrades. A missing file causes docker compose config to fail immediately.

The production Compose file uses the latest image and fixed host ports for HTTP 8080, RTMP 1935, and STUN 3478/udp. Container-only health port 8081 and metrics port 9090 are not published by the default Compose file.

Volumes

Compose uses volumes for:

• PostgreSQL data.
• Redis data.
• SyncTV /data runtime directory.

The Compose file fixes SyncTV’s data directory to /data:

environment:
  SYNCTV_DATA_DIR: /data

This directory may contain management socket runtime files, HLS files, proxy slice cache files, and other runtime-owned outputs.

Ports

Host mappings and container listeners are managed separately:

Host port	Container port	Purpose
8080	8080	HTTP REST + public gRPC
1935	1935	RTMP
3478/udp	3478/udp	STUN
No host mapping	8081	liveness/readiness for the container healthcheck
No host mapping	9090	Prometheus metrics for a collector on the container network

When a host port is already in use, change the host mapping in the Compose file and run docker compose config again.

Backups

Back up the PostgreSQL volume, all three environment files, and /data when persistent HLS or proxy slice cache is enabled. Preserve these values for the lifetime of the installation:

Environment variable	Purpose
SYNCTV_JWT_SECRET	Signs access, refresh, and guest tokens
SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET	Long-lived server secret for OPAQUE password authentication
SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY	Encrypts Provider credentials
SYNCTV_SECURITY_EMAIL_OUTBOX_ENCRYPTION_KEY	Encrypts queued email payloads in PostgreSQL
SYNCTV_BOOTSTRAP_ROOT_PASSWORD	Creates the initial root user

Caution

Reuse the secrets in .env.synctv for the lifetime of the installation. Existing password records depend on the OPAQUE secret; Provider credentials and queued email depend on their dedicated encryption keys.

Redis stores cache and shared state. Restoring or clearing Redis affects short-lived OAuth2 state, token blacklist entries, and rate-limit counters.

Common Failures

Symptom	Action
docker compose config reports missing variables or files	Keep all three environment files and docker-compose.yml in the same directory.
/health/ready fails	Run docker compose logs synctv and inspect the first startup error.
The root user cannot sign in	Confirm the root password was set before the first database startup and inspect bootstrap logs.
A host port is already in use	Change the host mapping in the Compose file, then run docker compose config again.
Prometheus cannot scrape metrics	Run Prometheus on the same Docker network, or add an explicit 9090 mapping for a trusted collector.

Before Production Traffic

• Complete the Production Checklist for TLS, backups, metrics, and alerts.
• Follow Upgrades and Migrations for image and database upgrades.
• See Configuration Fields and Environment Variables for complete settings.