Backups and restore

Backups and restore

Your collection is precious, so DVinyl lets you export it to a file and bring it back later. There are two kinds of backup, and the difference matters, so this page keeps them clearly apart.

	Collection backup	Instance backup
What it saves	One collection: its items and its settings	Everything: all users, all collections and their items, settings and login history
Who can make it	An admin of that collection	An admin of the whole instance
Where	The collection's admin page	The instance admin page
What restoring does	Replaces the items of the active collection	Replaces the entire instance and logs you out
File name	dvinyl_collection-<name>_<date>.json	dvinyl_instance_<date>.json

A simple way to remember it: a collection backup is one shelf; an instance backup is the whole house.

Collection backup

Use this when you want to save, move or share a single collection.

• What is inside: every item of the collection, plus that collection's own settings (enabled media types, themes, widget layout...). It does not contain any user accounts, and it does not carry internal ids, so the file is safe to import into a different collection or even a different instance.
• Export: open the collection's admin page, find the Collection backup section, and click Export. A .json file downloads.
• Import: in the same section, click Import and pick a backup file.

Warning

Importing a collection backup replaces every item of the collection you are currently in. The items already there are removed first, then the file's items are added. Make sure the right collection is active before you import, and export a fresh backup first if you are unsure.

Good reasons to use a collection backup:

• Snapshot a collection before a big cleanup or bulk edit.
• Move one collection from a test instance to your real one.
• Hand a collection's contents to a friend running their own DVinyl.

Instance backup

Use this to save or migrate your whole DVinyl server in one file.

• What is inside: all users, every collection with all of its items, every collection's settings, and the login logs. One file, the complete picture.
• Export: open the instance admin page, find the Instance backup section, and click Export.
• Import: in the same section, click Import and pick the file.

Caution

Importing an instance backup wipes and replaces the entire instance (all users, all collections, everything) with the content of the file. You will be logged out at the end. To restore just one collection, use its own collection backup instead (above), not this.

Good reasons to use an instance backup:

• Regular safety backups of your server.
• Moving DVinyl to a new machine or a new Docker host.
• Disaster recovery after a database problem.

Restoring onto a brand-new instance

You do not need to be logged in to restore an instance backup on a fresh install: on the very first run, the setup screen lets you upload an instance backup to seed the server (users and all) in one step. This is the intended way to migrate to a new machine.

Coming from an older DVinyl (before multiple collections existed)? Your old whole-instance export still works: DVinyl detects the older format on import and automatically upgrades it, rebuilding a default collection and re-attaching your items to it. You do not have to convert anything by hand.

Note

A collection backup cannot bootstrap a fresh instance on its own, because it contains no user accounts. To set up a new server, restore an instance backup first, then import collection backups into it if you need to.

Which one should I use?

• "I want to save my whole server." → Instance backup.
• "I'm moving to a new machine." → Instance backup (restore it from the setup screen).
• "I want to copy or share one collection." → Collection backup.
• "I'm about to do something risky to one collection." → Collection backup of that collection.
• "I'm upgrading from an old DVinyl version." → Your old instance export imports as-is; DVinyl migrates it for you.

---

Back to the Wiki home.