Docker Compose Deployment

Two Compose Files

The repository provides two Compose files:

File	Purpose	Behavior
docker-compose.dev.yml	Local development	Builds from the local Dockerfile and includes development secrets
docker-compose.yml	Image-based deployment	Uses zijiren/synctv:latest and requires explicit production secrets

Startup Modes

Development Compose

Start:

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

This starts:

• PostgreSQL 18.
• Redis 8.
• SyncTV built from the local Dockerfile.

It includes development-only JWT, cluster, credential encryption, OPAQUE, and root password values.

Production Compose

Generate persistent environment files before first startup:

./scripts/init-compose-env.sh

Edit SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv, then start:

docker compose config
docker compose up -d

Docker Compose loads required .env.postgres and .env.synctv files through env_file: PostgreSQL reads only database variables, and synctv reads only application settings. Back up both files and reuse them across restarts, new shells, host reboots, and upgrades. If either file is missing, docker compose config fails immediately.

When upgrading, update the image tag in docker-compose.yml or pin the desired image in your own Compose override file.

Caution

Do not copy development Compose secrets into production. Production Compose requires explicit secrets by design.

Volumes

Compose uses volumes for:

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

/data corresponds to:

SYNCTV_DATA_DIR=/data

This directory may contain:

• Management socket runtime files.
• HLS files.
• Proxy slice cache files.
• Other runtime-owned outputs.

Ports

Default exposed ports:

Host port	Container port	Purpose
8080	8080	HTTP REST + gRPC + health checks
1935	1935	RTMP
3478/udp	3478/udp	STUN

If a host port conflicts, edit the Compose port mapping.

Health Check

Compose checks:

http://localhost:8080/health/ready

If health checks fail, inspect logs:

docker compose logs -f synctv

Common Questions

Why does production Compose require secrets?

Because weak automatic defaults are unsafe. The service should not accidentally start in production with known secrets.

Users cannot log in after changing SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET

That secret must remain stable. Changing it can make existing OPAQUE password records unverifiable.

What should be backed up?

At minimum:

• PostgreSQL volume.
• Production secrets.

Depending on enabled features:

• /data HLS files.
• Proxy slice cache.

Redis is usually short-lived shared state, but losing it can affect OAuth2 state, token blacklist, and rate-limit counters.