Configuration Validation

Primary Commands

Local binary:

synctv config --config synctv.yaml validate --strict

Development via Cargo:

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

If the service starts but access, authentication, media playback, or Ingress behavior is wrong, start from Troubleshooting.

config validate reports unknown config-file keys and unsupported SYNCTV_ environment variables as warnings by default. Use --strict for deployment preflight because synctv serve uses the same strict unknown-input policy at startup.

Common Errors

OPAQUE Secret Is Empty

Meaning: security.opaque_server_setup_secret is not configured.

Set the secret:

export SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET="$(openssl rand -base64 48)"

Save this value in production. Do not regenerate it on every deployment.

Credential Key Format Is Invalid

security.credential_encryption_key must be 64 hexadecimal characters.

Generate:

openssl rand -hex 32

Wrong examples:

• Base64 strings.
• Human passwords.
• Any value whose length is not 64 hex characters.

CORS Origin Is Invalid

Correct:

server:
  cors_allowed_origins:
    - "https://app.example.com"

Wrong:

server:
  cors_allowed_origins:
    - "https://app.example.com/path"

CORS origins cannot include paths.

WebAuthn Origin Is Invalid

webauthn.rp_origin must also be an origin without path, query, or fragment.

Cluster Enabled but Redis Missing

cluster.enabled=true requires Redis.

Set Redis:

redis:
  url: "redis://redis:6379"

Cluster Enabled but Cluster Secret Missing

Set the cluster secret:

export SYNCTV_CLUSTER_SECRET="$(openssl rand -hex 32)"

Compose Debugging

First make sure you got the production Compose files from Docker Compose Deployment, then generated .env.postgres, .env.redis, and .env.synctv in the same directory.

Inspect final Compose config:

docker compose config

Inspect logs:

docker compose logs -f synctv

If Compose reports a required variable missing, production Compose expects explicit secrets. Return to the Compose file directory, run ./scripts/init-compose-env.sh, and fill the root password in .env.synctv.

Helm Debugging

Render manifests:

helm template synctv ./helm/synctv --values my-values.yaml

Lint:

helm lint ./helm/synctv

Inspect runtime ConfigMap:

kubectl get configmap synctv-config -n synctv -o yaml

List Secret keys:

kubectl get secret synctv-secrets -n synctv -o jsonpath='{.data}' | jq 'keys'

Do not paste Secret values into issues or chat.