Upgrading OSS from 3.14 to 3.15

upgrade

#1

I have read the instructions at

Upgrading Nexus Repository Manager 3.1.0 and Newer

Either I am missing something or it’s very confusing:

Perform the Upgrade

  1. Ensure you have taken recent backups of the existing Data Directory and any custom blobstore locations according to our recommended practices. Because of involved Upgrade steps, downgrading a NXRM version is not supported and will almost always result in failures. If you have issues, restore from this backup instead.
  2. Stop your existing install using the scripts under ./bin or your operating system service. Make sure it stops completely.
  3. Start the new installation using the scripts under ./bin or adjust your operating system service to use these scripts.
  4. Review the log files for any possible issues and sign-in to the server to confirm things are working as expected.

Nowhere in those instructions does it mention how to actually perform the upgrade. Maybe, I can’t tell for certain, the expectation is to change the service files to point to the newly extracted version but then there are no instructions on how to import any configuration, blobs, database, etc. with the exception of a couple configuration settings in .vmoptions.

So, I’m completely stuck on how to do an upgrade. Can anyone point me to more complete documentation?


#2

The article you’ve referenced provides instructions for configuring the new version to use your existing data directory (by setting the karaf.data property). Once you’ve done this, starting up the new version will cause the upgrade to be performed.

Regards,

Rich


#3

Thanks for the clarification; the linked document would benefit from some additional discussion based on your reply. I’m going to add some more commentary here that others searching this topic might find useful - at least I would have found it useful in my search or in the linked document.

What wasn’t clear to me was that the process describe leads to “the upgrade to be performed”. It isn’t really an upgrade; it’s a new installation that has been set to point to the old data; it’s implied, but not clearly so.

The extracted sonatype-work directory is pretty much empty except some folder structure so extracting the latest on top of the existing doesn’t change any of your data; extraction just gives you a new app directory, nexus-3.15.2-01 in my case today.

A couple gotchas in the extraction process. In one of the docs I read on upgrading it was suggested to run as the account that will execute nexus in production because that account should own the files. But it’s not possible for that account to do the work unless you’re running as root (don’t even consider doing that) because no account except root should be allowed to create new files/directories in /opt. Permissions in /opt should be drwxr-xr-x with owner being root:root. A better solution is to use sudo to copy/extract/modify all your files and then chown -R mysvcacct:mysvcacct allmysonatypedirs to fix ownership.

Now you have a couple of choices. The article suggests changing your OS service config to point to the new app directory, a reasonable choice. I run my instance in a version-agnostic directory structure so I don’t have to update my OS config or my documentation. My structure is /opt/sonatype/nexus and opt/sonatype/sonatype-work. Making sure, as the instructions stated, that the existing instance is not running, I next renamed the existing opt/sonatype/nexus directory using mv ./nexus ./nexus-3.14-bak. Then I copied the new directory to nexus using cp -rf ./nexus-3.15.2-01 ./nexus.

Be sure to follow the instructions regarding manual changes to copy config from the old instance to the new instance, in particular the settings in nexus.vmoptions. The article suggests copying any other changes you made in the $nexus_home/etc directory. That’s a big directory so there are a lot of possibilities. I don’t recommend copying the files from old to new in case there are new settings so it would be nice if Sonatype had a diff tool just for this purpose.

One more difference I had that wasn’t mentioned at all in the article - there could be more missed settings but only this one applied to my case: if you’ve changed the run_as_user setting (you’re not running as root, right?) you have to do that again in ./nexus/nexus.rc.

I restarted the service (I’m using RHEL 7) using sudo systemctl start nexus.service and I was instantly running the new version; there was no visible “upgrade process”. If there was code executing to upgrade config or the database, it completed before I could get a browser connected to check my running version.

I hope this helps take away some of the upgrade fear for others trying to do the same thing.