Skip to content
SyncTVSyncTV Docs

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

Section titled “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

Section titled “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 TAR archive.

Deployment settings

Download files

The archive is ready to download.

The generator provides three environment files in a TAR archive:

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

“Download TAR” creates a TAR archive containing all three environment files. Random secrets are generated in page memory and never written to browser storage or the server.

Install

Section titled “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/main/docker-compose.yml -o docker-compose.yml

  2. Return to Generate Environment Files, download synctv-compose-env.tar, and put it in the current directory.

  3. Extract the environment files. Their names start with ., so Linux treats them as hidden files; use ls -a to view them:

    终端窗口
    tar -xf synctv-compose-env.tar
    ls -a

  4. Validate the final Compose configuration:

    终端窗口
    docker compose -f docker-compose.yml config --quiet

  5. 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

Section titled “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

Section titled “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 and RTMP 1935. The built-in STUN server is disabled by default. Container-only health port 8081 and metrics port 9090 are not published by the default Compose file.

Volumes

Section titled “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

Section titled “Ports”

Host mappings and container listeners are managed separately:

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

To host the built-in STUN server, set SYNCTV_WEBRTC_ENABLE_BUILTIN_STUN=true, configure a client-reachable SYNCTV_WEBRTC_STUN_EXTERNAL_ADDR, and add 3478:3478/udp to the SyncTV service’s ports list.

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

Backups

Section titled “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

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

Common Failures

Section titled “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

Section titled “Before Production Traffic”