This guide covers keeping a CloudSOE Nexus Repository instance patched on both AWS and Azure: operating-system updates, upgrading Nexus itself, and moving your data to a fresh CloudSOE image when that’s the cleaner option. The image runs on Ubuntu 26.04 LTS and doesn’t include PHP, so PHP2Shell doesn’t apply.
What you can upgrade in place
| Component | In place? | How |
|---|---|---|
| Operating system (Ubuntu 26.04 LTS) | Yes | apt (see Update the operating system) |
Nexus Repository (tarball in /opt/nexus) | Yes, with care | Swap in the new release, keep /opt/sonatype-work (see Upgrade Nexus) |
Java (bundled with Nexus in /opt/nexus/jdk) | Comes with Nexus | Nexus runs on the JDK shipped inside its own tarball, so upgrading Nexus is what updates its Java. The OS openjdk-17-jdk package is patched by apt but Nexus doesn’t use it. |
| Embedded H2 database | Comes with Nexus | Migrated automatically the first time the new release starts |
| A release older than 3.71 still on OrientDB | No | Migrate the database first (see the warning below), or ask CloudSOE support |
Moving to a fresh image is the better route if you’d rather not touch a production server, or if the instance has drifted a long way from the shipped layout. See Move to a fresh CloudSOE image.
Before you start: back up
Take both a cloud snapshot and a Nexus-level backup. The snapshot is your one-click rollback; the tarball is what you restore onto a new instance.
Cloud disk snapshot
- AWS: EC2 → Volumes → select the instance’s root volume → Actions → Create snapshot.
- Azure: your VM → Disks → select the OS disk → Create snapshot.
If you’ve attached a separate data disk for blob stores, snapshot that too. For a fully consistent snapshot, stop Nexus first (sudo systemctl stop nexus).
Nexus backup
Everything Nexus knows lives in /opt/sonatype-work/nexus3 (blob stores, database, etc/nexus.properties). The per-instance encryption key at /opt/nexus/nexus.secrets.json sits outside it and is just as important: without it, restored proxy passwords, tokens and LDAP binds can’t be decrypted.
sudo systemctl stop nexus
sudo tar czf /home/$(whoami)/nexus-backup-$(date +%F).tar.gz \
/opt/sonatype-work/nexus3 /opt/nexus/nexus.secrets.json /opt/nexus/bin/nexus.vmoptions
sudo chown $(whoami): /home/$(whoami)/nexus-backup-*.tar.gz
chmod 600 /home/$(whoami)/nexus-backup-*.tar.gz
sudo systemctl start nexus
The chmod matters: the tarball contains the encryption key, so it should be readable only by you.
Check there’s room first (df -h /), since the tarball is roughly the size of your blob stores. If you created blob stores on another disk, add their paths to the tar command. Copy the backup off the instance (S3, Azure Blob, your workstation) before you change anything.
Update the operating system
OS packages come from Ubuntu’s repositories. Patch on your own schedule:
sudo apt update
apt list --upgradable
sudo apt upgrade
If an update needs a reboot, Ubuntu creates /var/run/reboot-required:
[ -f /var/run/reboot-required ] && cat /var/run/reboot-required.pkgs
sudo reboot
Nexus is enabled at boot and takes two to three minutes to come back afterwards. Once you’ve rebooted into a new kernel, sudo apt autoremove clears out the old one.
Automatic security updates. Ubuntu normally runs unattended-upgrades for security fixes, and the CloudSOE build doesn’t switch it off. Check what your instance is doing:
systemctl status unattended-upgrades
cat /etc/apt/apt.conf.d/20auto-upgrades
It installs packages but doesn’t reboot, so keep an eye on /var/run/reboot-required.
Held packages. apt-mark showhold lists anything pinned at its current version. A held package won’t get security fixes, so release holds you no longer need with sudo apt-mark unhold <package>.
Stay on Ubuntu 26.04. Don’t run do-release-upgrade on this instance. When you want a newer Ubuntu release, move to a fresh CloudSOE image instead.
Upgrade Nexus
The image installs Nexus from Sonatype’s Linux tarball: program files in /opt/nexus, data in /opt/sonatype-work/nexus3, both owned by the nexus user, run by the nexus systemd service. Upgrading means swapping the program files and leaving the data where it is. The new release finds /opt/sonatype-work/nexus3 through the default -Dkaraf.data=../sonatype-work/nexus3 setting in bin/nexus.vmoptions.
Before you upgrade:
- Check your current version. It’s shown in the Nexus UI, and in
VERSIONin/etc/cloudsoe-support.txtfor the version the image shipped with. Current CloudSOE images ship Nexus 3.80. - Releases older than 3.71 need a database migration first. Nexus 3.71 and later don’t run on the old OrientDB database. If your instance is older than 3.71, list
/opt/sonatype-work/nexus3/dbfirst: an H2 database shows up as anexus.mv.dbfile. If you don’t see one, follow Sonatype’s OrientDB migration documentation before installing any 3.71+ release, or contact CloudSOE support. - Read Sonatype’s release notes for every release between your version and the target. They list required intermediate versions and behaviour changes.
- You can’t downgrade. Once a newer release has started on your data, rolling back means restoring the backup, not just the old program files.
Upgrade steps. Find the current release on Sonatype’s download page (https://help.sonatype.com/en/download.html). The Linux download is named nexus-<version>-linux-x86_64.tar.gz.
# 1. Download and unpack the new release
cd /tmp
wget https://download.sonatype.com/nexus/3/nexus-<version>-linux-x86_64.tar.gz
mkdir /tmp/nexus-new
tar -xzf nexus-<version>-linux-x86_64.tar.gz -C /tmp/nexus-new
# 2. Stop Nexus and move the old program files aside (keep them for rollback)
sudo systemctl stop nexus
sudo mv /opt/nexus /opt/nexus-old
# 3. Put the new program files in place
sudo mkdir /opt/nexus
sudo cp -a /tmp/nexus-new/nexus-<version>/. /opt/nexus/
# 4. Bring the per-instance encryption key across. Nexus won't decrypt your secrets without it.
sudo cp -a /opt/nexus-old/nexus.secrets.json /opt/nexus/nexus.secrets.json
sudo chmod 600 /opt/nexus/nexus.secrets.json
# 5. Re-apply any JVM changes you made (heap size etc.) to the new nexus.vmoptions
sudo diff /opt/nexus-old/bin/nexus.vmoptions /opt/nexus/bin/nexus.vmoptions
# 6. Fix ownership and start
sudo chown -R nexus:nexus /opt/nexus
sudo systemctl start nexus
In step 5, only copy across lines you changed yourself, such as -Xms, -Xmx and -XX:MaxDirectMemorySize. Keep the new release’s version of everything else. Port and host settings live in /opt/sonatype-work/nexus3/etc/nexus.properties and don’t need to move.
The first start on a new release can take longer than usual while Nexus migrates its database. Watch it with:
sudo tail -f /opt/sonatype-work/nexus3/log/nexus.log
When everything checks out (see Check everything works), clean up with sudo rm -rf /opt/nexus-old /tmp/nexus-new /tmp/nexus-*-linux-x86_64.tar.gz.
Rolling back. Stop Nexus, put /opt/nexus-old back as /opt/nexus, restore /opt/sonatype-work/nexus3 from your backup tarball, then start Nexus. Or restore the cloud snapshot.
About the nexus-upgrade helper
The image also ships /usr/local/sbin/nexus-upgrade, which automates the same swap:
sudo nexus-upgrade # latest release
sudo nexus-upgrade 3.81.0-08 # or a specific release
On images published from November 2026, it backs up /opt/nexus and /opt/sonatype-work once to /opt/nexus-backups/<date-time>, checks free space against the real size of your data, verifies the download’s checksum where Sonatype publishes one, carries your encryption key and changed nexus.vmoptions settings into the new release, keeps the old install as /opt/nexus-old-<date-time>, and waits for Nexus to answer before it reports success. If Nexus doesn’t come up, it prints the exact commands to roll back.
Instances launched before November 2026 have an older version of the helper that leaves the encryption key behind with the old install and copies your data twice. On those, use the manual steps above. If you have already run the old helper, check that /opt/nexus/nexus.secrets.json exists; if it doesn’t, copy it back and restart:
sudo cp -a /opt/nexus-old/nexus.secrets.json /opt/nexus/
sudo chown nexus:nexus /opt/nexus/nexus.secrets.json
sudo systemctl restart nexus
Move to a fresh CloudSOE image
A fresh image gets you the latest Ubuntu patches, the current Nexus release and a clean layout in one step. The old instance keeps running until you switch over.
1. Back up the old instance. Stop Nexus and create the tarball exactly as in Before you start. Leave Nexus stopped if you want no new uploads to land on the old server during the move.
2. Launch the latest image. Follow the getting-started guide for AWS or Azure. Size the disk for your blob stores. Wait for first boot to finish before you restore anything, or the first-boot service will later overwrite the key you restore:
ls /var/lib/nexus-firstboot.done && systemctl status nexus
You don’t need to run the setup wizard on the new instance. Your restored data brings its own users and settings.
3. Copy the backup across. Copy it from your workstation (or directly between the instances if they can reach each other):
scp <admin-user>@<old-ip>:nexus-backup-<date>.tar.gz .
scp nexus-backup-<date>.tar.gz <admin-user>@<new-ip>:
For very large blob stores, create a volume from the old instance’s snapshot, attach it to the new instance and copy locally. That’s usually faster than copying over the network.
4. Restore on the new instance.
sudo systemctl stop nexus
sudo mv /opt/sonatype-work/nexus3 /opt/sonatype-work/nexus3.fresh # the new instance's empty data
sudo tar xzf /home/$(whoami)/nexus-backup-<date>.tar.gz -C / \
opt/sonatype-work/nexus3 opt/nexus/nexus.secrets.json
sudo chown -R nexus:nexus /opt/sonatype-work /opt/nexus/nexus.secrets.json
sudo chmod 600 /opt/nexus/nexus.secrets.json
sudo systemctl start nexus
The restored nexus.secrets.json replaces the new instance’s key. This is intended: your data was encrypted with the old key. Re-apply your heap settings to /opt/nexus/bin/nexus.vmoptions. Don’t overwrite the new release’s file with your old one wholesale. To read the old copy from the backup:
tar xzf /home/$(whoami)/nexus-backup-<date>.tar.gz -O opt/nexus/bin/nexus.vmoptions | grep -E '^-X'
Sign in with your existing admin password, not a new admin.password.
If the new image runs a newer Nexus release than the old instance, the database is migrated on this first start. The same version rules apply as for an in-place upgrade: data from a release older than 3.71 must be migrated off OrientDB first.
Once you’ve checked everything, remove the placeholder with sudo rm -rf /opt/sonatype-work/nexus3.fresh.
5. Switch clients over. Build tools, settings.xml / .npmrc / pip.conf files, Docker daemon configs, CI variables and any reverse proxy or load balancer all point at the old address. Choose one:
- Move the address. AWS: EC2 → Elastic IPs → re-associate the Elastic IP with the new instance. Azure: dissociate the static public IP from the old VM’s NIC and associate it with the new one.
- Update DNS. Point your Nexus hostname at the new instance. Lower the record’s TTL a day in advance.
- If Nexus sits behind a load balancer or Application Gateway, swap the target or backend pool member instead.
If you’ve set a base URL under Administration → System → General, check it still matches the address clients use.
6. Retire the old instance. Keep it stopped, not deleted, for a few days in case something was missed. Then terminate it (AWS) or delete the VM with its disks, NIC and any public IP you didn’t reuse (Azure). Delete the old snapshots and backup tarballs once you no longer need them for rollback.
Check everything works
Run these after any OS update, Nexus upgrade or migration:
# Service up and listening
systemctl status nexus
sudo ss -ltnp | grep 8081
# Status endpoints: both should return HTTP 200
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/service/rest/v1/status
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/service/rest/v1/status/writable
# Running version (Server header)
curl -sI http://localhost:8081/ | grep -i '^server'
# Errors during startup or migration
sudo grep -iE 'error|exception' /opt/sonatype-work/nexus3/log/nexus.log | tail -n 20
# The encryption key is in place
sudo ls -l /opt/nexus/nexus.secrets.json
Then, from your own machine:
- Browse to
http://<public-ip>:8081and sign in with your existing admin account. - Under Administration → System → Status, review the system status checks.
- Open a proxy repository that uses stored credentials. If it can still reach its remote, your secrets were decrypted correctly.
- Run a real build (
mvn,npm install,docker pull) against the instance.
Next steps
- Configure Nexus: file locations, ports, memory, the encryption key and HTTPS
- Tips & tricks: the
nexus-upgradehelper, backups, disk management and troubleshooting