File System Layout

Everything Sovereign creates lives under a single directory, /sovereign-data, mounted from a volume you provide. Knowing what each directory holds, and how long its contents last, tells you what to back up, what’s safe to delete, and what to size your storage for.

Container Paths

Three paths matter inside the container:

/app - the application itself, baked into the image. Nothing here is yours to edit, and nothing written here survives replacing the container.
/sovereign-data - the persistent data volume, described in the rest of this page.
/media - your library, mounted read-only.

Only /sovereign-data needs persistent storage, and it’s the only path Sovereign writes to. Keep it on local disk or block storage; never on NFS, because SQLite and network file locking don’t mix.

The Data Directory

A running server has this shape:

Directorysovereign-data/
- sovereign.db Library, users, playback state
- server.json Values generated once, on first start
- installation.json Identity of this installation
- license.jws Signed license, once the server is activated
- Directoryassets/ Artwork, seek previews, subtitle images
  - Directoryimages/
    …
  - Directorytrickplay/
    …
  - Directorysubtitles/
    …
- Directorymedia/
  - Directoryvideos/ Transcoder scratch space
    …
- Directoryusers/ Per-account files
  - …
- Directorycertificates/ Token certificates
  - …
- Directorylogs/ Rolling server logs
  - …

The directories are created on first start if they don’t already exist, so an empty volume is a valid starting point.

Database

sovereign.db is the SQLite database. It holds your library metadata, accounts, playback progress, favourites, job history and everything else the application queries. Two sidecar files appear beside it while the server runs, sovereign.db-wal and sovereign.db-shm. Those belong to SQLite’s write-ahead log; treat all three as one unit and never copy or delete one on its own.

The database is created on first start and upgraded automatically when you move to a release that changes its shape. A daily maintenance job prunes records past their retention window (activity-log entries, devices that haven’t been seen in a while, client error reports, sent-mail history and storage samples), refreshes the query planner’s statistics and compacts the file to reclaim space.

Losing the database costs you accounts, watch history and favourites. The library itself is re-imported from your configured sources on the next start.

Server Identity Files

Three files sit loose in the root of the data directory and get their own mention because they carry identity rather than content:

server.json - values this install generates for itself on first start and must keep forever, including the alphabet for the IDs in links, the key that protects media links, the OAuth client ID for the web app, and the one televisions pair under. Regenerating any of them breaks something visible: bookmarked links stop resolving, in-flight asset URLs are rejected, browser sessions are signed out, and paired televisions have to pair again. Pinning a value through configuration overrides the stored one.
installation.json - identifies this installation.
license.jws - the signed license, present once the server holds a license.

They’re files rather than database rows so that they survive the database being reset. Sovereign manages all three; don’t hand-edit them, and don’t copy them into a second install.

Generated Assets

assets/ holds everything Sovereign derives from your library: artwork downloaded from metadata providers, seek-preview sprite sheets, and the rendered images for image-based subtitle tracks. Each type owns a subtree, and every subtree is bucketed into numbered shard directories so that no single directory ends up with tens of thousands of entries in it.

Artefact	Location
Artwork	`assets/images/{kind}/{shard}/{id}/{Type}.jpg`
Downscaled artwork	`assets/images/{kind}/{shard}/{id}/w{width}/{Type}.jpg`
Seek preview sprites	`assets/trickplay/{shard}/{mediaId}/{mediaFileId}/`
Subtitle images	`assets/subtitles/{shard}/{mediaId}/{mediaFileId}/`

{kind} separates artwork owned by a movie, a series, or a person, so that IDs drawn from different tables can’t collide and deleting one can’t take out another.

Each artefact is generated once, on demand, and reused from then on. Downscaled artwork works a little differently. A smaller copy is written the first time a client asks for that size, from a fixed set of sizes. Nothing here expires on a timer. Files stay as long as the database record that owns them does, deleting a title removes its directories, and a daily cleanup job reconciles the tree against the database to reclaim anything an interrupted delete left behind.

The whole tree is safe to delete. Everything in it can be produced again from your media and your metadata providers, though re-downloading artwork and re-analysing video takes time and load.

Transcoder Scratch Space

media/videos/ is working space for playback. Every stream uses it, including one that plays without transcoding, because even an untouched file is repackaged as HLS before it reaches the player. Each stream gets its own directory, keyed by viewer, media file and stream, and FFmpeg writes the HLS playlists, the segments and the session’s text subtitle cues into it while playback runs.

None of it is meant to last:

Segments fall away behind the playhead as playback advances, leaving enough behind for a viewer who seeks backwards. How much is worked out per session from what the playback client reports about its own buffering, so there’s nothing to configure.
The stream directory is deleted when the stream is evicted, which happens shortly after a client stops sending heartbeats.
The whole directory is emptied on both shutdown and startup, so a crash can’t leave stale segments behind.

Size this for the streams you expect at once rather than for the size of your library, and give it your fastest disk. It’s the hottest write path in the application. Don’t back it up, and don’t put it on network storage.

Sovereign checks free space on this directory’s volume and on the data volume every hour, and warns administrators when either runs low. The thresholds and how to change them are under Disk Space.

Per-Account Files

users/{userId}/ holds files belonging to a single account, which today means a profile picture stored as profile.<ext>. A user’s directory is created the first time they need one, and holds at most one picture. A new upload, or a picture brought in from a social sign-in, replaces the old file.

Certificates and Keys

certificates/ holds the certificates the token server uses to sign and encrypt tokens. An install upgraded from an earlier release may also have key-*.xml files in it; nothing reads them any more, and they’re safe to delete. If you don’t supply your own certificates, Sovereign creates self-signed ones on first start and reuses them from then on, which is what lets sessions survive a restart. If you do supply them, the supplied certificate is written here and this copy is the one Sovereign uses, so a later restart that omits the setting still finds it.

Logs

logs/ holds the rolling server log, one file per day named sovereign-YYYYMMDD.jsonl, written as newline-delimited JSON. The 31 most recent files are kept and older ones are removed as new ones roll, so the directory has a bounded size. The Logs page in Admin Settings reads these files and can download them as an archive.

Your Media Library

Sovereign never writes to your media, so mount it read-only. Subtitle images, artwork and previews all land in assets/, not beside your files.

The path you mount it at has to match the paths your media sources report. Radarr and Sonarr hand over absolute file paths and Sovereign opens them as they are, with no rewriting in between, so if Radarr calls a film /media/movies/... then the Sovereign container has to see it at that same path. Mount the library at the same path in both containers. NFS Media Storage covers doing that when the library lives on another machine.

What to Back Up

Path	Back up	Notes
`sovereign.db`	✓	Include the `-wal` and `-shm` files
`server.json`	✓	Losing it breaks existing links and sessions
`installation.json`	✓	Identity of this install
`license.jws`	✓	Saves activating the server again
`certificates/`	✓	Restoring it keeps existing sessions valid
`users/`	✓	Profile pictures can’t be regenerated
`assets/`		Large, and rebuilt on demand
`media/videos/`		Transient by design
`logs/`		Rolls and prunes itself

Stop the container before copying the database, or take an atomic snapshot of the volume. Copying a live SQLite file with cp can capture a half-written page and give you a backup that only fails when you try to restore it.

To move accounts to a new install rather than restore a whole volume, use Export Backup on the Backup & Restore admin page, which packs every account’s settings, favourites, progress and profile picture, along with the server’s license, into one archive. Backups need a purchased license; see User Backups.

Titles, artwork, people and descriptions shown in screenshots are fictional and were created for illustration. Sovereign doesn't include or supply any media: it plays the library you bring.