Skip to content
SyncTV SyncTV Docs

SyncTV Documentation

Real-time synchronized watching, livestreaming, media aggregation, and horizontally scalable collaboration.
Quick Start Architecture Configuration Reference Client Integration

Documentation Layout

Section titled “Documentation Layout”

SyncTV can run as a self-hosted single-node service or as a multi-node cluster. The documentation is organized around four workflows:

  • Deployment: Docker Compose, Helm, production checklist, secrets, domains, ports, storage, and Ingress.
  • Configuration: Redis, PostgreSQL, CORS, rate limits, metrics, WebAuthn, OAuth2, cluster mode, cache, and providers.
  • Operations: backup and restore, upgrades, observability, logs, troubleshooting, and incident data collection.
  • Development: configuration precedence, environment variables, CLI, OpenAPI, gRPC, provider configuration, and deployment templates.

Start Quickly

Bring up PostgreSQL, Redis, and SyncTV with Docker Compose, then verify the required production secrets.

Understand Boundaries

Learn how HTTP/gRPC, management, metrics, Redis, PostgreSQL, provider proxying, and clustering fit together.

Understand Configuration

Every configuration page explains what the field controls, when to change it, and what operational risk it carries.

Deploy to Production

Review Helm, Ingress, split HTTP/gRPC services, metrics, Redis, HLS storage, and multi-replica constraints.

Security Defaults

JWT, OPAQUE, provider credential encryption, CORS, trusted proxies, rate limits, and WebAuthn have dedicated pages.

Core Configuration Principles

Section titled “Core Configuration Principles”

SyncTV configuration is built around three rules: keep stable secrets stable, inject sensitive values through secret mechanisms, and put runtime-owned files under a persistent data directory.

Key concepts:

  • jwt.secret: signs login tokens. Rotate it if it leaks; existing sessions may be invalidated.
  • security.opaque_server_setup_secret: used by OPAQUE password authentication. Keep it stable across restarts and upgrades.
  • security.credential_encryption_key: encrypts media provider credentials. Back it up securely before storing encrypted credentials.
  • data_dir: root directory for runtime-owned files such as the management socket, logs, HLS files, and proxy slice cache.
  • server.cors_allowed_origins: allowed browser origins for cross-origin API access.
  • cluster.enabled: enables multi-node coordination. Redis and server.cluster_secret become required.
Section titled “Recommended Reading Order”
  1. Read Quick Start and confirm the service can start.
  2. When writing configuration, use the Full Configuration Example and Configuration Index.
  3. Read How Configuration Works to understand precedence and environment variable naming.
  4. For server deployments, read Security and Secrets.
  5. For Docker or Kubernetes, read Docker Compose Deployment or Helm Deployment.
  6. Before production launch, read Backup and Restore, Upgrades and Migrations, and Observability Runbook.
  7. Before managing users, rooms, permissions, or providers, read Administration Runbook and Rooms, Permissions, and Preferences.
  8. Before building a client or SDK, read the Client Integration Guide.
  9. For production data governance, read Data, Privacy, and Retention.
  10. For startup, Ingress, authentication, or media playback failures, start from Troubleshooting.

Common Entry Points

Section titled “Common Entry Points”
Documentation Map Task-oriented entry points for deployment, configuration, operations, development, and troubleshooting.
Configuration Index All configuration fields, types, defaults, and links to detailed explanations.
Architecture Overview Single-binary service, network surfaces, state layers, provider proxying, slice cache, and cluster model.
Authentication and Security Model Local login, OAuth2, user 2FA, token context, management control plane, and provider header boundaries.
Administration Runbook Management boundaries for users, rooms, reviews, providers, runtime settings, system state, and slice cache.
Rooms, Permissions, and Preferences Global roles, room roles, permission bits, room settings, member overrides, and user preferences.
Client Integration Guide HTTP, gRPC, WebSocket, login, MFA, OAuth2, tokens, and media header integration guidance.
Production Checklist Review secrets, database, Redis, Ingress, metrics, backups, and upgrades before launch.
Data, Privacy, and Retention PostgreSQL, Redis, logs, backups, PII, provider credentials, and background cleanup behavior.
Observability Runbook Health checks, metrics, logs, key alerts, and incident data collection.
Troubleshooting Diagnose startup, configuration, Ingress, authentication, provider, cache, livestream, and cluster issues.
CLI Reference Manage users, rooms, providers, settings, system state, and slice cache from the CLI.
Runtime Settings Reference Database hot-reload setting keys, defaults, validation rules, and scope.
OpenAPI Access Enable the openapi feature and access Swagger UI or the OpenAPI JSON document.

License

Section titled “License”

SyncTV is licensed under the MIT License. See the repository LICENSE file for the full terms.