Quick Start

Requirements

For local development or single-node deployment, Docker Compose is the fastest path. It starts:

• postgres: the primary SyncTV database.
• redis: shared state for cache, rate limits, OAuth2 state, and cluster coordination.
• synctv: the main service process. HTTP, gRPC, RTMP, and STUN are served by the same binary.

Production needs at least these secrets:

Name	Purpose	Recommended generation
SYNCTV_JWT_SECRET	Signs access and refresh tokens	openssl rand -base64 32
SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET	Stable OPAQUE password-auth secret	openssl rand -base64 48
SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY	Encrypts provider credentials; must be 64 hex chars	openssl rand -hex 32
SYNCTV_BOOTSTRAP_ROOT_PASSWORD	Initial root account password	Generate with a password manager

Caution

security.opaque_server_setup_secret and security.credential_encryption_key are long-lived secrets. Do not regenerate them on every deployment.

Choose a Startup Mode

Dev Compose

1. Start development Compose:

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

2. Check service status:

   docker compose -f docker-compose.dev.yml ps
   docker compose -f docker-compose.dev.yml logs -f synctv

3. Run a management command inside the container:

   docker compose -f docker-compose.dev.yml exec synctv synctv system stats

Production Compose

1. Generate a persistent env files:

   ./scripts/init-compose-env.sh

2. Edit SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv, then start services:

   docker compose config
   docker compose up -d

3. Check health:

   docker compose ps
   docker compose logs -f synctv

Local Binary

1. Start PostgreSQL and Redis:

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

2. Validate configuration:

   cargo run -p synctv --bin synctv -- config validate

3. Start the service. Startup runs embedded SQLx migrations automatically:

   cargo run -p synctv --bin synctv -- serve

Development Compose

For local testing:

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

Development Compose includes working development secrets. Do not use those values in production.

Check logs:

docker compose -f docker-compose.dev.yml ps
docker compose -f docker-compose.dev.yml logs -f synctv

Production Compose

Production Compose intentionally refuses to start without explicit secrets. Generate and keep persistent .env.postgres and .env.synctv files in the repository root:

./scripts/init-compose-env.sh

Edit SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv, then start:

docker compose config
docker compose up -d

Docker Compose reads required .env.postgres and .env.synctv files through env_file. PostgreSQL reads only database variables, and synctv reads only application settings. If either file is missing, docker compose config fails immediately.

Validate Configuration

With a local config file:

cargo run -p synctv --bin synctv -- config --config synctv.yaml validate

Validation checks:

• YAML parsing.
• JWT secret strength.
• OPAQUE secret presence and placeholder detection.
• Redis, OAuth2, WebAuthn, and cluster dependency consistency.
• Ports, paths, timeouts, and rate-limit ranges.

First Login

When bootstrap.create_root_user=true, SyncTV creates a root user if the database does not already contain one.

Default username:

bootstrap:
  root_username: "root"

Password sources:

• bootstrap.root_password in the config file.
• SYNCTV_BOOTSTRAP_ROOT_PASSWORD.
• SYNCTV_BOOTSTRAP_ROOT_PASSWORD_FILE.

Use environment variables or secret files in production. Do not commit the root password.