15h ago

Upgrading Paperless-ngx several revisions behind

Hey everyone. For a variety of reasons I’ve ended up with a paperless-ngx install that has not been upgraded for a while. It’s currently on 1.17.1, and I’ve been researching to figure out the best way to get back up to current. I’m worried about major changes that have happened over time and what the best way to go about this is, but I’ve not had good luck finding something that gives me the confidence to go about it. Hoping someone here has some guidance. Cheers!

10 comments

I’ve not had good luck finding something that gives me the confidence to go about it
Now's a good time to make sure you have good backups.
Knowing you can fallback to your backups helps a lot with confidence.
- In addition to backups, consider using snapshots if your file system supports it (ZFS, Btrfs, or LVM).
  I use ZFS and have each of my Docker volumes in a separate ZFS dataset (similar to a Btrfs subvolume). This lets me snapshot each container independently. I take a snapshot before an upgrade. If the upgrade goes badly, I can instantly revert back to the point before I performed the upgrade.
- Having the ability to shut down the main instance of an app and run a secondary instance from backups without much hassle is the best feeling ever, I recently updated from Nextcloud v26 to v31, and having the ability to just go back to a working version if anything was wrong saved me from so much stress.
- fallback
  That's the noun. For the verb, it's "fall back", with a space.

This is how I handle it for most software: Read (or at least skim) the changelogs for all minor and major versions between your current version and the latest version.
If you're using Docker, diff your current docker-compose to the latest one for the project. See if any third-party dependencies (like PostgreSQL, Redis, etc) have breaking changes.
If there's any versions with major breaking changes, upgrade to each one separately (eg. 1.0 to 2.0, then 2.0 to 3.0, etc) rather than jumping immediately to the latest one, as a lot of developers don't sufficiently test upgrading across multiple versions.
Take a snapshot before each upgrade (or if your file system doesn't support snapshots, manually take a backup before each upgrade).
...or just don't read anything, YOLO it, and restore a snapshot if that fails. A lot of software is simple enough that all you need to do is change the version number in docker-compose (if you're using Docker).

I haven't gone through your specific case, but generally what I do when doing a major update with potentially breaking changes:
Read the upgrade guides, if they have them. Some devs will put them out if they know their users will encounter issues when upgrading. If they don't have an upgrade guide, there might be some in the change logs. Going from 1.17.1 to (assuming) 2.x.y, check the change logs at 2.0.0.
Backup everything. I'd recommend doing this on a regular basis anyway.
(If you're running it in a docker container) Setup a second instance, restore the backup, then run the upgrade. You'll be able to check to see if it breaks at all. If it works, you can just destroy the old one and use the new one
(if you're not running it in a container) with the backup, try upgrading. If it breaks, you should be able to uninstall & reinstall the old version, then restore the backup
- Looking through the docs n' stuff, this is what I found:
  Updating Guide. Just basic steps, similar to what I explained above; but with commands to run.
  Backing up and restoring
  2.0.0 Change Log. Unfortunately they don't include any notes about how to upgrade
  I wasn't able to find any additional instructions on how to update other than the expected generic steps (docker pull or pip install -r requirements.txt). So my guess at this point is that they have scripts built in to check the version and run upgrade scripts as needed
- Yeah, these are pretty solid advice, would say that you should be safe with patch version updates, like from 1.17.1 to 1.17.4
  Should be able to jump from 1.17.4 to 2.0.1 and from 2.0.1 to 2.1.3, etc. going straight to the last patch of the next version, but should go one by one minor version, paying close attention to those versions that have breaking changes in the release notes. And always backup and test before each version jump.

Paperless provides an export tool that lets you export all your documents. There's no guarantee that the import will work on a higher version, but usually it's fine. Just make sure that you have a clean install without any documents before importing from an old export.
It's also possible to export all documents and metadata via the REST API, though that's a bit fiddly. Then you can import them the same way. Again, this should only be done into an empty system, because otherwise your object IDs will be all scrambled up.

In these cases I'll do the same thing other people here seem to do as well. Do a backup (or snapshot) and then I'll try to just do it. Obviously read the documentation on updates and major version upgrades first. I think that's fine in the case of paperless-ngx.
Either it works or it doesn't. In that case I'll gather error logs and information for debugging and roll back to the backup. After a successful major upgrade, I often go through the settings and config and check about all the things that have been added or changed in the meantime and make sure they're set to my liking.

10 comments