Add backup and restore guide to documentation

blog/2024/10-26-jellyfin-release-10.10.0/index.mdx

@@ -10,7 +10,7 @@ We are pleased to announce the latest stable release of Jellyfin, version 10.10.
 
 This major release brings several new features, improvements, and bugfixes to improve your Jellyfin experience. With our faster release cadence between 10.9.0 and 10.10.0, this release should be far less daunting, so please read on for a quick peek at what's new and some important-to-know breaking changes!
 
-You may upgrade your Jellyfin instances at any time now. For those who were running Unstable builds for testing, we thank you immensely, and you may now switch back to the Stable repository and forcibly reinstall/repull the latest version. As always, **ensure you [back up your Jellyfin data and configuration directories](/docs/general/testing/upgrades#make-backups) before upgrading**. With a major release, it's possible you will hit a bug and want to revert, and to do so, you will need to restore from a backup.
+You may upgrade your Jellyfin instances at any time now. For those who were running Unstable builds for testing, we thank you immensely, and you may now switch back to the Stable repository and forcibly reinstall/repull the latest version. As always, **ensure you [back up your Jellyfin data and configuration directories](/docs/general/administration/backup-and-restore) before upgrading**. With a major release, it's possible you will hit a bug and want to revert, and to do so, you will need to restore from a backup.
 
 Happy watching!
 

docs/general/administration/backup-and-restore.md

@@ -0,0 +1,74 @@
+---
+uid: backup-and-restore
+title: Backup and Restore
+---
+
+# Backup and Restore
+
+This guide documents how to both back up and then restore the data in your Jellyfin instance.
+
+## Why Backing Up is Important
+
+Backups are important in general for all digital data. There are myriad possible bugs and issues that can arise and cause data loss, especially when you upgrade major releases (for instance, from Jellyfin 10.9.x to Jellyfin 10.10.x).
+
+In addition, Jellyfin does not have a downgrade mechanism. This is very important to understand; once your Jellyfin instance has been started with a new version, any pending migrations are immediately applied, and your Jellyfin data will no longer work with the old version. The **only** way to restore your active instance back to the old version is to restore a backup. Backups are thus critical if you want to test Unstable versions, or before upgradiing to the latest version. In fact, when testing Unstable, it is best to back up much more regularly, perhaps using a cron job or similar automatic mechanism, to ensure that your data can be recovered if you hit a major issue.
+
+Backups may also come in handy if you hit a bug. For instance, if a bug in the new version causes corruption of some aspect of the Jellyfin data, restoring from a backup means you can quickly restore to good data and apply any fixes to avoid a repeat. Without a backup, you would be completely out of luck in this situation.
+
+Finally, administrative mistakes, normal operation issues (e.g. filling up a disk), or general bit rot can cause corruption or issues that require a backup to be restored. It's always better to have one than not.
+
+## Taking a Backup
+
+1. Stop the running Jellyfin server. This is extremely important, as otherwise the database will be locked and might not be recoverable when restoring. Note that this will interrupt any playback.
+
+   * Any platform: Within the Jellyfin Dashboard, click "Shutdown". This should cleanly stop the process on all platforms, but if not, try one of the following.
+   * Docker: `docker stop jellyfin`
+   * Debian/Ubuntu packages: `sudo systemctl stop jellyfin` or `sudo service jellyfin stop`
+   * Windows Installer: Right-click the Tray app, and select "Quit"; or, in Process Manager, find the Jellyfin process and terminate it.
+   * MacOS Installer (.dmg): In Activity Monitor, find the Jellyfin process and terminate it.
+   * Portable Installs (regardless of platform): Stop the running `jellyfin` or `jellyfin.exe` program, however it was started.
+
+2. Copy your data and configuration directories to a destination of your choice. What you name the copies is up to you; personally, I like to use dated and versioned directory names e.g. `jellyfin.2024-05-01_10.8.13`. Where these files are also depends on the platform; generally these follow the [XDG Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) for platforms that support it. For more information see [the configuration documentation](/docs/general/administration/configuration/#server-paths).
+
+   **NOTE**: These are default locations; if you've changed your data or config paths, use those instead.
+
+   * Official Docker: Wherever your `/data` and `/config` volumes are sourced from; this is set in your `docker-compose.yml` or in your `-v` options to `docker run`.
+   * LinuxServer.io Docker: Data and config are wherever your `/config` volume is sourced from; this is set in your `docker-compose.yml` or in your `-v` options to `docker run`.
+   * Debian/Ubuntu packages: Data is in `/var/lib/jellyfin` and config is in `/etc/jellyfin`; these are defined in `/etc/default/jellyfin`.
+   * RPMFusion Fedora/CentOS packages: Data is in `/var/lib/jellyfin` and config is in `/etc/jellyfin`; these are defined in `/etc/sysconfig/jellyfin`.
+   * Windows Tray/Installer (.exe): Data and config is in `%PROGRAMDATA%\Jellyfin\Server` (`C:\ProgramData\Jellyfin\Server`) or `%LOCALAPPDATA%\Jellyfin` (`C:\Users\<Username>\AppData\Local\Jellyfin`).
+   * MacOS Installer (.dmg): Data is stored in one of these paths; back up whichever one(s) exist: `~/.config/jellyfin/`, `~/.local/share/jellyfin/`, `~/Library/Application Support/Jellyfin/`.
+   * Portable Installs:
+      * Linux: Data is stored in `~/.local/share/jellyfin` and config in `~/.local/share/jellyfin`.
+      * Windows: Data and config is in `C:\Users\<Username>\AppData\Local\Jellyfin`, using `%LOCALAPPDATA%`.
+      * MacOS: Data is stored in these paths; back up whichever one(s) exist: `~/.config/jellyfin/`, `~/.local/share/jellyfin/`, `~/Library/Application Support/Jellyfin/`.
+
+   As an example, on Debian, you can do this with these commands to make a copy of both directories into a single target directory:
+
+   ```bash
+   TIMESTAMP=$(date +%Y%m%d%H%M%S)
+   VERSION=10.9.10
+   sudo mkdir -p /media/backups/jellyfin.${TIMESTAMP}_${VERSION}  # Or change the path wherever in your system makes sense to you
+   sudo cp -a /var/lib/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/data
+   sudo cp -a /etc/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/config
+   ```
+
+3. Start up Jellyfin again, either after upgrading or on the current version. You now have a safe copy of your data in the path chosen in step 2.
+
+## Restoring a Backup
+
+This process assumes you followed the steps above to take the backup.
+
+1. Stop the running Jellyfin server process.
+
+2. Move your current data and configuration directories out of the way (e.g. by appending `.bak` to them). For example, `sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak` and `sudo mv /etc/jellyfin /etc/jellyfin.bak`.
+
+3. Copy - **do not move or rename** - your backup to the existing name. For example, `sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/data /var/lib/jellyfin` and `sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/config /etc/jellyfin`.
+
+4. If required, downgrade Jellyfin to the same version as your backup now.
+
+5. Start up Jellyfin again. It should start cleanly with the old data, assuming versions are correct. If you downgraded this may happen automatically.
+
+## The Future
+
+Long-term, we have plans to provide an official backup and restore plugin bundled with Jellyfin, however this requires the completion of our EFCore rewrite, which is currently slated for our next major release 10.11.0. Once that becomes available, this document will be updated to reflect the process using that plugin.

docs/general/testing/upgrades.md

@@ -37,9 +37,7 @@ The only way to downgrade from an Unstable to an older Stable is to restore from
 
 You can utilize certain plugins to help with this, for instance the Trakt plugin to synchronize watched status, but this will not necessarily preserve everything. So be careful here, and know the limitations before proceeding.
 
-How to back up your server depends on the exact platform, as each platform stores data in different places. [The exact locations are documented here](/docs/general/administration/configuration/#server-paths).
-
-**Ensure you stop Jellyfin from running before taking a backup**. If you don't, the database might still be locked and this can cause problems when restoring.
+Follow [the process listed in the documentation here](/docs/general/administration/backup-and-restore) for more details.
 
 ### Disable Automatic Updates on Unstable
 

docs/index.md

@@ -47,6 +47,7 @@ Want to know more about administering a Jellyfin server? Check out these pages!
 
 - [Quick-Start Guide](/docs/general/quick-start): What to do after you have installed Jellyfin to get it up and running.
 - [Migrating](/docs/general/administration/migrate): How to migrate Jellyfin.
+- [Backup and Restore](/docs/general/administration/backup-and-restore): How to back up or restore your Jellyfin metadata and configuration.
 - [Plugins](/docs/general/server/plugins): How to install and manage plugins.
 - [Networking](/docs/general/networking): Networking settings and troubleshooting.
 - [Monitoring](/docs/general/networking/monitoring): Integration with external monitoring software.