Quick Start

This path is for single-node production: one SyncTV process, one PostgreSQL instance, and one Redis instance. For Kubernetes or multiple replicas, complete this path first, then read Helm Deployment and Cluster Configuration.

Prerequisites

• Docker and Docker Compose are available.
• openssl and python3 are available for the env initializer.
• The current directory can permanently store Compose files, .env.postgres, .env.redis, .env.synctv, and volumes.
• You have an initial root password. Use a password manager in production.

Start

1. Create a directory and download the Compose files:

   mkdir synctv-compose
   cd synctv-compose
   curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/docker-compose.yml
   curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.postgres.example
   curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.redis.example
   curl -fsSLO https://raw.githubusercontent.com/zijiren233/synctv/next/.env.synctv.example
   mkdir -p scripts
   curl -fsSL https://raw.githubusercontent.com/zijiren233/synctv/next/scripts/init-compose-env.sh -o scripts/init-compose-env.sh
   chmod +x scripts/init-compose-env.sh

2. Generate .env.postgres, .env.redis, and .env.synctv:

   ./scripts/init-compose-env.sh

3. Edit .env.synctv and set the root password:

   SYNCTV_BOOTSTRAP_ROOT_PASSWORD=replace-with-a-strong-password

4. Check the rendered Compose config:

   docker compose config

5. Start the service:

   docker compose up -d

Verify

docker compose ps
curl -fsS http://localhost:8080/health/ready

Then open:

http://localhost:8080

The default root username is root. Its password comes from SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv.

Values To Keep

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_BOOTSTRAP_ROOT_PASSWORD	Creates the initial root user

Caution

Do not delete or regenerate the long-lived secrets in .env.synctv. Changing SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET or SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY can make existing password records or Provider credentials unusable.

Common Failures

Symptom	Action
docker compose config reports missing variables	Run ./scripts/init-compose-env.sh and keep .env.postgres, .env.redis, and .env.synctv in the current directory.
/health/ready fails	Run docker compose logs -f synctv and inspect the first startup error.
Browser CORS errors	Set SYNCTV_SERVER_CORS_ALLOWED_ORIGINS in .env.synctv; use origins only.
Root user cannot log in	Confirm SYNCTV_BOOTSTRAP_ROOT_PASSWORD was set before first database startup and inspect bootstrap logs.

Continue Reading

• Complete the Production Checklist for TLS, backups, metrics, and alerts.
• Read Docker Compose Deployment for Compose file, port, and volume details.
• For local source development, read Development Guide.