diff --git a/blog/2024/10-26-jellyfin-release-10.10.0/index.mdx b/blog/2024/10-26-jellyfin-release-10.10.0/index.mdx index 3195d8337..eea690fb6 100644 --- a/blog/2024/10-26-jellyfin-release-10.10.0/index.mdx +++ b/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! diff --git a/docs/general/administration/backup-and-restore.md b/docs/general/administration/backup-and-restore.md new file mode 100644 index 000000000..79782bc78 --- /dev/null +++ b/docs/general/administration/backup-and-restore.md @@ -0,0 +1,72 @@ +--- +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. Within Jellyfin, as mentioned above, there is always a possibility of bugs showing up, 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: `sudo 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`. + * RPMFusion Fedora/CentOS packages: Data is in `/var/lib/jellyfin` and config is in `/etc/jellyfin`. + * Windows Tray/Installer (.exe): Data and config is in `C:\ProgramData\Jellyfin\Server` or `C:\Users\\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\\AppData\Local\Jellyfin`. + * 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: + + ``` + sudo mkdir -p /media/backups/jellyfin.2024-10-27_10.9.11 # Or change the path wherever in your system makes sense to you + sudo cp -a /var/lib/jellyfin /media/backups/jellyfin.2024-10-28_10.9.11/data + sudo cp -a /etc/jellyfin /media/backups/jellyfin.2024-10-28_10.9.11/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. + +4. 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 + +Some members of the team are working on a plugin to handle exporting the database without a server shutdown or manual copy operation. Once this is done, our goal is to bundle this plugin by default, but have it disabled by default, allowing administrators the flexibility to configure this as needed and enable it as it suits them. This document will be updated once that becomes available. diff --git a/docs/index.md b/docs/index.md index 5948cbeca..e1f0fe79c 100644 --- a/docs/index.md +++ b/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.