Storage, backups and restoring

Settings → Server → Storage answers the question every server eventually asks: what do I have to back up? It lists every place Credenza writes to, says which ones cannot be rebuilt, and exports the ones that matter as a zip file you download.

Only administrators, and accounts given the Export backups permission, can open it.

Where your data lives

Each row shows the folder Credenza is actually using — whether you chose it on this page or in the configuration — whether it exists and can be written to, how much space is free on that disk, and what losing it costs.

Place	Losing it costs	Moving it
Database	Everything: libraries, accounts, watch history, requests, settings and every match you fixed by hand	Not from this page: it is wherever the connection string points
Game saves	Every game’s progress — they exist nowhere else	Saves already written stay behind; copy them across first
Sign-in keys	Everyone is signed out once	The keys are copied across, so nobody is signed out
Logs	The log history	New lines go to the new folder; older files stay where they were
Exported backups	The backups themselves	Backups already exported stay where they are
Artwork cache	Nothing — artwork downloads again	The old cache is left behind and downloads again into the new folder
Transcoding scratch	Nothing — it is deleted as each stream ends	Applies from the next stream
Web app	Nothing — it comes with Credenza	Not from this page: it is part of the install

To move a folder, press Change on its row, enter an absolute path (or browse to one) and save. Credenza checks it can write there before accepting it. Use default puts a moved folder back. Changing a folder needs the Change server settings permission as well as Export backups.

The database and game saves are marked Back this up: they are the two things that cannot be rebuilt from your media. The page also says which places sit outside the data folder (/data in the Docker image, /var/lib for a Linux package). If you move game saves to another disk, a backup of the data folder alone stops covering them — the page is where you find out.

The database row shows its host, port and name, never its username or password.

Exporting a backup

1. Under Backups, choose what to include. Database and Game saves are on by default. Logs and the Artwork cache are off; the artwork cache can be large and downloads again by itself. Transcoding scratch is never included.
2. Select Export. The server builds the zip in the background, so you can leave the page; the list shows Being built, then Ready.
3. Select Download to save the file.

Only one backup is built at a time. Before it starts, the server checks there is room for it and says how much it needs if there is not. The newest five finished backups are kept, and older ones are deleted as new ones finish. Backups are saved in the Backups folder shown at the bottom of the page; move it to another disk there, and copy the files somewhere other than this machine — a backup on the same disk is lost with it.

A backup holds everything

The zip contains every account’s password hash, every API key, and the credentials for TMDB, ScreenScraper, IGDB, Radarr and Sonarr. Keep it as safe as the server itself.

The Android app cannot save files, so download backups from a web browser.

When the database can’t be exported

Credenza dumps the database with PostgreSQL’s own pg_dump, which must be at least as new as the database server. If the page says no usable pg_dump was found, the Database box is disabled with the reason. You can still export game saves and logs.

• Docker: the image includes the client. If you see this message, your database container is newer than the image — update both.
• Linux package with the Docker database: sudo credenza-setup installs the matching client. Run it again if you installed Credenza before backups existed.
• Linux package with this machine’s PostgreSQL: the client comes with the server and is found automatically.
• Anything else: install the PostgreSQL client tools of the same major version as your database (for PostgreSQL 18, postgresql-client-18 from the PostgreSQL project’s apt repository), or set MediaServer__Backups__PgDumpPath to the pg_dump to use.

What’s in the zip

File	What it is
manifest.json	The server version, the database schema version, when the backup was made and by whom, what it contains, and the PostgreSQL and extension versions it came from
database.dump	The database, in pg_dump’s custom format
game-saves/	The game save folder
logs/	The log files, if you chose them
artwork/	The artwork cache, if you chose it

The sign-in keys are not included, so after a restore everyone signs in again once.

Restoring a backup

There is no restore button. Restoring replaces the whole database, so it is done by hand while Credenza is stopped. The database you restore into needs the same three extensions Credenza always needs — pgmq, pg_search (preloaded) and pgvector — at least at the versions in manifest.json. The Credenza database image has them, and so does a PostgreSQL that credenza-setup prepared.

Restore as a database superuser into an empty database, and keep the dump’s owners — that is, do not pass --no-owner. Done this way pg_restore finishes with no errors.

Unpack the backup first:

unzip credenza-backup-20261005-210000-abcd1234.zip -d restore

Docker Compose

From the folder holding docker-compose.yml:

docker compose stop credenza
docker compose exec -T postgres dropdb -U credenza --force --if-exists credenza
docker compose exec -T postgres createdb -U credenza credenza
docker compose exec -T postgres pg_restore -U credenza -d credenza --exit-on-error < restore/database.dump
cp -a restore/game-saves/. data/credenza/credenza/game-saves/
docker compose start credenza

The Compose database’s credenza user is its superuser, so nothing else is needed. If you changed POSTGRES_USER or POSTGRES_DB, use those names.

Linux package, Docker database

sudo systemctl stop credenza
sudo docker exec -i credenza-postgres dropdb -U credenza --force --if-exists credenza
sudo docker exec -i credenza-postgres createdb -U credenza credenza
sudo docker exec -i credenza-postgres pg_restore -U credenza -d credenza --exit-on-error < restore/database.dump
sudo cp -a restore/game-saves/. /var/lib/credenza/game-saves/
sudo chown -R credenza:credenza /var/lib/credenza/game-saves
sudo systemctl start credenza

The user and database names are in /etc/credenza/postgres.env.

Linux package, this machine’s PostgreSQL

Here Credenza’s own role is not a superuser, so the restore runs as postgres into a database owned by credenza:

sudo systemctl stop credenza
sudo cp restore/database.dump /tmp/credenza.dump && sudo chmod 644 /tmp/credenza.dump
sudo -u postgres dropdb --force --if-exists credenza
sudo -u postgres createdb -O credenza credenza
sudo -u postgres pg_restore -d credenza --exit-on-error /tmp/credenza.dump
sudo rm /tmp/credenza.dump
sudo cp -a restore/game-saves/. /var/lib/credenza/game-saves/
sudo chown -R credenza:credenza /var/lib/credenza/game-saves
sudo systemctl start credenza

The extensions and the grants Credenza’s role needs on pgmq’s tables are part of the dump. Run sudo credenza-setup first if this PostgreSQL has never had Credenza’s extensions installed.

After restoring

Start Credenza and open /status; Database and Background work should be healthy. If the backup came from an older version of Credenza, the server brings the database up to date as it starts. Restore logs or artwork the same way as game saves if you exported them — or leave the artwork out and let it download again.

A backup made on one machine restores on another. Media is never in the backup, so the new machine needs your media at the same paths the libraries point to, or you edit each library’s folders after restoring.