Server documentation

The Sofa King server keeps live TV, recordings and media libraries for the app and other players. These pages are Sofa King thorough; start with getting started.

Guides

Page	What it covers
Getting started	From docker compose up to a channel playing in Plex, the Sofa King app or an M3U player
Deploy with Docker	Installing with Compose, Unraid, Synology or Portainer, the config folder, running as your own user, secrets, reverse proxies, serving the web app, the published image and its provenance, and automatic updates
Build a starter lineup	From an empty server to a grouped lineup of the free services with fallbacks across them, plus your local channels, and a lineup built by hand without a policy
Admin portal	The web pages at /admin: the home page and setup, channel edits, merges, required stations, groups, the sources and provider priority, devices and pairing, Plex, recordings, media libraries, the runtime and effective settings, and the System pages for updates, jobs, events and a support snapshot
Operations	State and backups, restore, upgrades and rollback, monitoring, logs, native provider failures, AI assistants and token rotation
Notifications	Sending recordings, source health, low disk, updates and new library files to ntfy, an Apprise API server or a webhook, such as Home Assistant, and checking a webhook's signature
Use with Sonarr, Radarr and Bazarr	The media layout the three share, path mapping, hook tokens, the Webhook and Emby / Jellyfin connections that queue a scan when a file changes, and Bazarr's subtitles
Troubleshooting and FAQ	Symptoms and fixes for startup, tokens, sources, the guide, players, Plex, recordings, media libraries and reverse proxies, and common questions

Reference

Page	What it covers
Server configuration and live TV	Every environment variable, source files, source identity, the lineup, logos, player outputs and Plex Live TV
Recordings	Recording a program or a series, the schedule, what happens while a recording runs, playing recordings, commercial breaks, cleanup and the recording states
Media libraries	The media folder, how to name movies, shows and other videos, .nfo files and artwork, details from TMDB, scans, intros, playback and hardware transcoding
Virtual channels	Channels the server plays from the libraries on a schedule: slots, shuffles, time slots, filler, the guide and how they stream
Native providers	The built-in clients for free streaming services, their options and their failure modes
Lineup policy	The policy file that rebuilds the whole lineup, its fields, runs, required stations, findings, API and the generator
Source health	Probes, failure classes, quarantine and recovery, source selection, and manual disables
HTTP API	Endpoints for clients, recordings, media libraries and library playback, the player outputs, the HDHomeRun routes, the admin API, errors and the types the app shares
Security	The intended deployment, which credential opens which routes, request limits, outbound requests and a hardening checklist
Architecture	Modules, data flow, storage, guide imports, playback, logos, the HDHomeRun remux and the logic behind each subsystem

Contributing

Page	What it covers
Development	Running without Docker, build and test, code conventions, the smoke scripts and adding a native provider
Dependencies	Pinned versions and the server-only update notes

The server's README introduces it. The repository's CONTRIBUTING covers the conventions the server shares with the app and CI, and its SECURITY how to report a vulnerability. The app's documentation covers the client that reads the API.

Glossary

The terms the server shares with the app (lineup, channel or lineup entry, group, program, guide, playback session) are in the repository glossary. These are the server's own:

Term	Meaning
Provider	One entry in sources.json: an M3U playlist, or a native client for one free streaming service. Each has an ID, such as pluto
Guide source	An XMLTV source of programs that the server imports. A provider can bring its own, and sources.json can list more
Candidate	A channel as one provider lists it, before it is in the lineup
Source	One stream URL a provider lists for a channel. Health is tracked per source, and a channel can have several, from any providers, in failover order. The API calls sources offerings
Station	One channel as the viewer sees it. The lineup policy builds one station from all the candidates that share a station key, a normalized form of the name, and serves it as one lineup entry
Lineup policy	The policy.json file that, with sources.json, decides the whole lineup
Series rule	A title the DVR records every airing of, on one channel or any
Recordings folder, media folder	SOFA_RECORDINGS_DIR, where the DVR writes its recordings, and SOFA_MEDIA_DIR, the read-only folder media libraries are added from
Device, tuner	An HDHomeRun device is what Plex adds, one per server port. Each device has SOFA_HDHR_TUNERS tuners, the streams it may play at once