Backup and Restore

Backup Scope

Production deployments must back up two categories of data:

Data	Required	Reason
PostgreSQL	Required	Users, rooms, permissions, provider instances, preferences, audit data, and business data live there
Production secrets	Required	JWT, OPAQUE, credential encryption, cluster, and management secrets affect login and decryption
Configuration files	Strongly recommended	Restore requires exact listeners, domains, dependencies, paths, and feature flags
Shared HLS storage	As needed	Required if you need to preserve HLS files or shared multi-replica segments
Proxy slice cache	Usually no	It is reproducible cache; losing it only lowers hit rate
Redis	Usually not long-term	Redis stores short-lived auth, rate-limit, and coordination state

Caution

Do not lose security.opaque_server_setup_secret or security.credential_encryption_key. The first affects OPAQUE password verification, and the second affects encrypted provider credentials.

Back Up PostgreSQL

pg_dump

Good for small and medium deployments:

pg_dump \
  --format=custom \
  --file=synctv-$(date +%Y%m%d-%H%M%S).dump \
  "$DATABASE_URL"

Restore:

createdb synctv_restore
pg_restore \
  --dbname=postgresql://synctv:password@localhost:5432/synctv_restore \
  --clean \
  --if-exists \
  synctv-20260504-120000.dump

plain SQL

Use this when you want readable SQL or already have an SQL-based backup system:

pg_dump "$DATABASE_URL" > synctv-$(date +%Y%m%d-%H%M%S).sql

Restore:

psql "$DATABASE_URL" < synctv-20260504-120000.sql

Kubernetes

If PostgreSQL runs inside Kubernetes, port-forward and back up locally:

kubectl -n synctv port-forward svc/postgres 5432:5432
pg_dump --format=custom --file=synctv.dump "$DATABASE_URL"

You can also use your platform’s native database backups, such as cloud snapshots, operator backup jobs, or object-storage archives.

Back Up Secrets

Store at least these values:

Setting	Recommended storage
jwt.secret	Secret Manager, Kubernetes Secret, password manager
security.opaque_server_setup_secret	Secret Manager, offline encrypted backup
security.credential_encryption_key	Secret Manager, offline encrypted backup
server.cluster_secret	Kubernetes Secret or Secret Manager
management.auth_token	Secret Manager
metrics.auth.*	Monitoring system secret
email.smtp_password	Secret Manager
Provider token/API key/cookie	Secret Manager or encrypted database storage

If you use _file settings, back up the file contents, not just the paths.

Restore Order

1. Stop SyncTV to avoid writes during restore.
2. Restore production secrets exactly as they were.
3. Restore configuration files or deployment values.
4. Restore PostgreSQL.
5. Restore shared HLS storage if needed.
6. Start the same SyncTV version and run synctv db status.
7. If upgrading, follow Upgrades and Migrations for configuration, image, and rollback-risk checks.
8. Start the service. Startup runs embedded SQLx migrations automatically, then check /health/ready, login, provider access, WebSocket, and metrics.

Restore Validation

After restoring, run:

synctv db status
synctv config validate
curl -fsS http://localhost:8080/health/ready

Business checks:

• Root/admin users can log in.
• 2FA-enabled users can complete login.
• Stored provider credentials decrypt and can reach upstream services.
• Rooms, members, playlists, and permissions are present.
• WebAuthn challenge and origin settings work if enabled.
• OAuth2 redirect state reads and writes through Redis if enabled.

Restore Drill Frequency

Recommended:

• Run a restore drill before each major upgrade.
• Run one after changing secret-management strategy.
• Periodically confirm backups can be read, decrypted, and imported.

Do not stop at “backup job succeeded”. A useful backup restores into a SyncTV instance that can log in, play media, and be administered.

Impact of Redis Loss

Redis loss does not usually destroy durable business data, but it changes short-term behavior:

• OAuth2 state expires and users must restart OAuth2 login.
• WebAuthn challenges expire and users must retry authentication.
• Email codes expire and must be resent.
• Token blacklist is lost, so revoked JWTs may remain valid until expiry.
• Rate-limit counters reset.
• Cluster nodes must register and catch up again.

If strong token revocation is required, use highly available Redis and keep token lifetimes short.