Backups, migrations, and upgrades

Create complete Cove backups, upgrade native or Docker installs, restore safely, and verify recovery.

Know what each backup contains

A recoverable Cove backup has more than one part. Keep at least one copy outside the machine or storage pool that runs Cove.

Each backup protects a different part of the installation.

Part	What it preserves	What it does not preserve
Backup Database	Library metadata and relationships, users, roles, permissions, saved state, history, and database-backed extension data	Config files, installed extension files, generated assets, and source media
Backup Config	cove-config.json, including library paths and server settings	The database, installed extension files, generated assets, and source media
Config/home directory copy	Config, installed extensions, logs, and other files stored under the instance home	The database when PostgreSQL is stored elsewhere
Generated directory copy	Covers, thumbnails, previews, sprites, and other derived assets	Source media and database records; generated assets can usually be rebuilt

Built-in backups do not include source media. Back up irreplaceable media separately. The cache is disposable and does not need to be backed up.

Create a backup in Cove

Create both built-in backups before upgrades or other risky changes.

1. Let write-heavy scans, imports, downloads, and extension jobs finish.
2. Open Settings → Operations → Backup & Restore.
3. Select Run on Backup Database. Record the returned cove_backup_<timestamp>_manual.sql path and confirm the file is non-empty.
4. Select Run on Backup Config. Record the returned cove_config_<timestamp>_manual.json path.
5. Copy both files off the Cove host. For immediately usable extensions and generated assets, also make a consistent copy or storage snapshot of the instance config/home and generated directories.

Where backups are written

• Provided Docker compose files: Cove writes to /backups; the default host path is ${COVE_DATA_DIR}/backups. Logs and installed extensions are under ${COVE_DATA_DIR}/config, and generated assets are under ${COVE_DATA_DIR}/generated.
• Native app: backups default to backups under that instance's home directory. Cove Instance Manager keeps each instance home separate.
• Source run: backups default to $COVE_HOME/backups when COVE_HOME is set; otherwise they use the platform-local Cove data directory.

Upgrade Docker

Keep the compose file and the same COVE_DATA_DIR value you used to create the deployment.

1. Read the release notes and check for version-specific instructions.
2. Create and copy out the database and config backups above.
3. Pull the new image, recreate the service, confirm its status, and review recent logs with the commands below. Use docker-compose.yml instead when that is your deployment's compose file.
4. If Cove shows Database Update Required, review the pending migrations and select Run Migration once. Cove creates one pre-migration database backup and applies the complete pending sequence before opening the library.
5. Keep the old backups until the upgraded instance passes verification.

COVE_DATA_DIR=/srv/cove docker compose --file docker-compose.allinone.yml pull
COVE_DATA_DIR=/srv/cove docker compose --file docker-compose.allinone.yml up --detach
COVE_DATA_DIR=/srv/cove docker compose --file docker-compose.allinone.yml ps
COVE_DATA_DIR=/srv/cove docker compose --file docker-compose.allinone.yml logs --tail 100 cove

Do not run docker compose down --volumes as an upgrade step. Deleting volumes is unnecessary and can remove data in customized deployments.

• Cove releases

Upgrade the native app

1. Read the release notes and create both built-in backups.
2. Stop the instance with Cove Instance Manager.
3. Install the new package from the latest release.
4. Start the same instance. If Cove shows Database Update Required, review the pending migrations and select Run Migration once. Cove backs up the database and applies the complete pending sequence before opening the library.
5. Verify the instance before deleting the previous installer or backup.

• Latest Cove release

Restore an existing installation

Restore only from a backup you trust, and keep a separate copy of the current files first. After a failed upgrade, restore with the Cove version that created the backup, verify it, and then retry the upgrade.

1. Put the backup files somewhere the Cove server can read. With the provided Docker setup, copy them into ${COVE_DATA_DIR}/backups on the host and refer to them as /backups/<filename> in Cove.
2. Open Settings → Operations → Backup & Restore.
3. Under Restore Backup, enter the database backup path, acknowledge that the current database will be replaced, and select Run.
4. Cove creates a pre-restore database backup, replaces the database, and reloads.
5. If needed, restore the config snapshot under Restore Config. Cove makes a pre-restore config snapshot before replacing cove-config.json, then reloads.
6. Restore saved config/home and generated-directory files when they were part of the recovery plan, preserving ownership and permissions compatible with the Cove process.

On a brand-new instance, the first-run wizard also offers Restore Cove Backup. It accepts a database backup and an optional config backup, then continues through owner setup.

Verify an upgrade or restore

1. Confirm login, user roles, and expected access rules.
2. Open representative library items and play media.
3. Run a small selective scan and confirm it completes.
4. Test search, saved filters, and expected metadata relationships.
5. Check generated covers or previews and one important extension.
6. Open Settings → Operations → Jobs and Settings → System Info → Logs for failures.

Keep the pre-upgrade and pre-restore backups until login, scan, search, generated media, and important extensions have all worked in normal use.