Backups and upgrades

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

Know what each backup contains

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

The 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

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. Copy the instance config/home directory and generated directory too when you want installed extensions and generated assets available immediately after recovery. Stop Cove for those filesystem copies, or use a consistent storage snapshot, then start it again.

Backup paths depend on the deployment:

• 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 shows and 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 and recreate the service:

   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

   Use docker-compose.yml instead when that is the compose file for your deployment.

4. Wait for startup and automatic database migrations to finish before starting scans or imports.

5. Keep the old backups until the upgraded instance passes verification.

Do not run docker compose down --volumes as an upgrade step. The provided bind mounts are persistent, but deleting volumes is unnecessary and can remove data in customized deployments.

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 and allow startup migrations to complete.
5. Verify the instance before deleting the previous installer or backup.

Restore an existing installation

Restore only from a backup you trust, and keep a separate copy of the current files first.

If you are recovering from a failed upgrade, restore with the Cove version that created the backup, verify it, and then retry the upgrade. Restoring an older database directly into a different application version can leave the schema and application out of step.

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, select I understand this will replace the current database with the selected backup, and select Run.
4. Cove creates a pre-restore database backup, replaces the database, and reloads.
5. If needed, enter the config snapshot under Restore Config, confirm replacement, and select Run. Cove makes a pre-restore config snapshot before overwriting cove-config.json, then reloads.
6. Restore the saved config/home and generated-directory files when those were part of your recovery plan. Keep their 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.