Documentation Map

This page organizes the documentation by task. It does not replace the configuration reference; it helps you decide which page to read first and what each section is meant to answer.

Tip

For a first deployment, follow the deployment path. For an existing service, jump directly to the task cards below.

Reader Paths

Deployer

1. Start with Quick Start and confirm the minimal Compose stack can boot.
2. Read Architecture Overview to understand the main service, management, metrics, Redis, PostgreSQL, and provider proxy boundaries.
3. Read How Configuration Works to understand defaults, config files, environment variables, and CLI overrides.
4. Start from the Full Configuration Example minimal production skeleton, then copy feature sections from the full template as needed.
5. Read Security and Secrets to replace example secrets and keep long-lived keys stable across restarts and upgrades.
6. Use Docker Compose Deployment or Helm Deployment depending on your runtime.
7. Before launch, run through the Production Checklist.
8. Complete Backup and Restore, Upgrades and Migrations, and Observability Runbook.
9. If you are building a client, SDK, or third-party integration, read the Client Integration Guide.
10. If you are designing data governance, privacy, or retention policy docs, read Data, Privacy, and Retention.
11. For startup, Ingress, authentication, or media playback failures, start from Troubleshooting.

Administrator

1. Read the CLI Reference for users, rooms, providers, system state, and configuration validation.
2. Read Administration Runbook to understand operational boundaries for users, rooms, reviews, providers, runtime settings, and system operations.
3. Read Rooms, Permissions, and Preferences to understand global roles, room roles, permission bits, room settings, and user preferences.
4. Read Authentication and Security Model to understand local login, OAuth2, 2FA, tokens, and the management control plane.
5. Read Runtime Settings Reference to know which policies are hot-reloadable and which require startup configuration.
6. Read Email and OAuth2 and WebAuthn and Passkeys for login, email codes, and MFA dependencies.
7. Read Rate Limits and Connection Limits to understand protections for login, verification codes, WebSocket, and API requests.
8. Read Metrics Monitoring and Observability Runbook before integrating Prometheus-compatible monitoring.

Developer

1. Read the Development Guide to prepare Rust, Node.js, PostgreSQL, Redis, SQLx, and the docs site.
2. Read OpenAPI Access for Swagger UI and OpenAPI JSON locations.
3. Read gRPC Debugging for cluster, admin, service protobuf, and reflection workflows.
4. Read the Client Integration Guide for login, MFA, WebSocket, OAuth2, and media header composition.
5. Use the Configuration Index when changing configuration structs.

Common Tasks

Run the service Start PostgreSQL, Redis, and SyncTV, then verify that the service is reachable.

Prepare production Review secrets, database, Redis, reverse proxy, Ingress, storage, monitoring, backups, and upgrades.

Understand architecture Single-binary service, network surfaces, state layers, media proxying, slice cache, and cluster model.

Understand authentication Password, WebAuthn, email, OAuth2, user 2FA, token context, and management control-plane boundaries.

Administer production Operational boundaries for users, rooms, reviews, providers, runtime settings, system state, and slice cache.

Understand permissions Global roles, room roles, permission bits, room settings, member overrides, and user preferences.

Troubleshoot failures Diagnose startup, configuration, deployment, authentication, proxy, livestream, and cluster issues by symptom.

Plan backups PostgreSQL, secrets, config files, HLS, Redis state, and restore drills.

Document data retention Personal data, provider credentials, audit logs, notifications, chat, backups, and background cleanup behavior.

Plan upgrades Migrations, Compose/Helm releases, rolling updates, config snapshots, and rollback risk.

Set up observability Health checks, metrics, logs, key alerts, and incident data collection.

Find a setting Browse fields, types, defaults, environment variables, and links to detailed pages.

Find a runtime setting Runtime setting keys, defaults, validation rules, sync semantics, and CLI examples.

Use a config template Use the minimal production skeleton and the full YAML example covering all static fields.

Understand config loading Learn defaults, files, environment variables, secret files, CLI overrides, and data_dir path resolution.

Deploy on Kubernetes Review Helm values, separate HTTP/gRPC Services, separate Ingresses, metrics, and external dependencies.

Connect media sources Configure Alist, Emby, Bilibili, direct URLs, provider instances, headers, and credential encryption.

Troubleshoot proxy cache Understand business caches, proxy slice cache, Range behavior, storage, TTL, and capacity controls.

Integrate with the API Enable the openapi feature and access Swagger UI or the OpenAPI JSON document.

Write a Client or SDK Login, MFA, OAuth2, WebSocket, gRPC room metadata, media headers, and token handling guidance.

Configuration Reading Order

The configuration pages are detailed. Read them by dependency and enabled feature, not as a single linear manual.

Core Runtime

Required Start with server listener, runtime paths, security secrets, database, and Redis.

Access Control

Continue with CORS, trusted proxies, rate limits, email, OAuth2, WebAuthn, and user security settings.

Media Features

If media providers or proxy cache are enabled, read provider, cache/proxy, livestream, and WebRTC pages.

Horizontal Scaling

For multi-replica deployments, read cluster, Redis, Helm, Ingress, HLS storage, and metrics pages.

Documentation Maintenance Checklist

• When adding a configuration field, update the Configuration Index, the Full Configuration Example, and the matching configuration topic.
• When adding a CLI command, update the CLI Reference.
• When changing deployment templates, update Docker Compose Deployment or Helm Deployment.
• When changing common errors, ports, Ingress behavior, authentication, or proxy behavior, update Troubleshooting.
• When changing runtime surfaces, dependencies, provider/proxy boundaries, or cluster behavior, update Architecture Overview.
• When changing login, 2FA, OAuth2, token, management, or permission boundaries, update Authentication and Security Model.
• When changing users, rooms, reviews, providers, runtime settings, or management CLI semantics, update Administration Runbook.
• When changing room roles, permission bits, room settings, member overrides, or user preferences, update Rooms, Permissions, and Preferences.
• When changing hot-reload fields registered in SettingsRegistry, update Runtime Settings Reference.
• When changing the OpenAPI feature, Swagger UI path, or OpenAPI JSON path, update OpenAPI Access.
• When changing cluster, admin, or service protobuf files, update gRPC Debugging.