Backups

Odeion has a built-in backup system in the admin panel. Backups capture database state: metadata, user accounts, watch history, settings, and library configuration. Media files are never included since they live on your filesystem and are identified by path at restore time.

The built-in system is sufficient on its own. You do not need to run pg_dump on the side or wire Odeion into an external backup tool.

What goes in a backup

When you create a backup you choose what to include:

• Users and authentication. Accounts, password hashes, invite codes.
• System settings. Server-wide configuration stored in the database.
• Full database dump. A complete pg_dump of the Odeion database, including everything above plus libraries, metadata, watch history, and any other table the server writes to.

The first two are captured as JSON inside the archive. The full database option shells out to pg_dump (bundled with the embedded Postgres build, or found on PATH when you bring your own Postgres) and stores the dump inside the archive.

Archives are written to the backups/ subdirectory of your data directory in either zip or tar.zst format.

Choosing between JSON-only and full database

The JSON-only options produce small archives and are well suited to routine snapshots: rotating settings, capturing a user list, moving accounts between installs. They restore quickly and do not depend on pg_restore.

The full database dump is the safer recovery option. It captures every table Odeion writes to, including tables that the JSON export does not know about, and it restores to a bit-for-bit equivalent database. Use it when:

• You are about to update Odeion to a new version.
• You are about to make schema or configuration changes you might want to roll back.
• You want a recovery point that does not depend on the current server version understanding an older JSON schema.

The trade-off is size. A full dump archive is typically much larger than a JSON-only archive, often by one or two orders of magnitude on a library with any real watch history. Plan retention and disk space accordingly.

Creating a backup

Go to Admin > Backups, click Create Backup, pick which components to include, and choose an archive format. The backup runs as a background task and appears in the list when it finishes. You can download archives directly from the admin panel.

Restoring a backup

There are two entry points:

During setup. On a fresh install the setup wizard offers a restore step before the first screen. Upload an archive and Odeion will restore from it and skip the rest of the wizard. Media paths on the new host must match the original, or you will need to fix up library roots after the fact.

From the admin panel. Open Admin > Backups, upload an archive if it is not already listed, and click Restore. You choose the restore mode:

• full_db replaces the entire database from the full dump.
• users_auth restores only accounts and authentication.
• settings restores only system settings.
• everything_json restores the JSON portions (users and settings) without touching anything else.

For the JSON modes you also pick a conflict strategy (skip, overwrite, rename) that controls how rows that already exist are handled.

A full_db restore requires pg_restore to be available. The admin panel shows whether the current server can restore a given archive before you start.

After any restore the server rescans libraries to reconcile the database against files on disk.

Avoiding expensive reprocessing

A database restore brings back metadata, but anything Odeion derives from the media files (thumbnails, transcodes, subtitle extracts, and so on) is still regenerated by post-restore scans. On large libraries this can take a while.

If you want to skip that work during disaster recovery, snapshot the entire Odeion data directory from the host, for example via a volume snapshot, filesystem snapshot, or an rsync of the mount. Restoring the data directory alongside the database avoids reprocessing because the derived files are already there.

This is outside the built-in backup system and Odeion does not manage it for you.

Recommendations

Take a full database backup before updating Odeion. Database migrations are designed to be safe, but a recent full dump is the cleanest rollback path if something goes wrong.

For routine snapshots between updates, JSON-only backups of users and settings are usually enough.