Tips & Tricks

Nexus Repository Tips & Tricks on CloudSOE Images

2026-07-30 · nexus-oss docs

A collection of practical advice for running the CloudSOE Nexus Repository image in production, on either cloud.

Upgrading with nexus-upgrade

The image ships an experimental helper that upgrades Nexus in place:

sudo nexus-upgrade

It prompts for confirmation, checks for at least 3 GB of free disk, stops the service, backs up /opt/nexus and /opt/sonatype-work to /opt/nexus-backups, downloads the latest Nexus 3 release from Sonatype, swaps it in with your configuration and data preserved, and restarts the service.

Take a cloud snapshot first — the script says so itself, and it’s right. For major version jumps, read Sonatype’s release notes before running it.

Back up the working directory

Everything Nexus knows lives in /opt/sonatype-work/nexus3 — plus the encryption key at /opt/nexus/nexus.secrets.json, without which restored secrets are unreadable. For a consistent copy:

sudo systemctl stop nexus
sudo tar czf /home/$(whoami)/nexus-backup-$(date +%F).tar.gz \
  /opt/sonatype-work/nexus3 /opt/nexus/nexus.secrets.json
sudo systemctl start nexus

Cloud snapshots (EBS on AWS, disk snapshots on Azure) are the low-effort complement and capture both paths at once.

Keep the disk under control

Proxy repositories cache everything your builds pull. Two built-in mechanisms keep growth in check:

  1. Cleanup policies (Administration → Repository → Cleanup Policies) delete old or unused components on a schedule.
  2. The Admin - Compact blob store task actually reclaims the space cleanup marked as deleted — cleanup without compaction frees nothing.

Watch free space with df -h / — Nexus misbehaves confusingly when the disk fills.

Security hardening

  • Disable anonymous access unless you’re intentionally running a public repository (Administration → Security → Anonymous Access).
  • Restrict port 8081 in your security group / NSG to your build infrastructure and your own IP range.
  • Create per-purpose users and roles instead of sharing admin — CI systems should use their own least-privilege accounts.
  • Put TLS in front for anything crossing the public internet — see the configuration guide.

Troubleshooting

Nexus takes two to three minutes to start — a connection refused right after a restart is usually just impatience. If it persists:

sudo systemctl status nexus
sudo tail -n 100 /opt/sonatype-work/nexus3/log/nexus.log
journalctl -u nexus-firstboot --no-pager   # first-boot key generation

The first-boot service is safe to re-run: its marker (/var/lib/nexus-firstboot.done) is only written on success.

The admin.password file is gone

That’s expected. /opt/sonatype-work/nexus3/admin.password exists only between first start and completing the setup wizard. If you’ve lost the admin password after the wizard, follow Sonatype’s documented recovery procedure rather than rebuilding.

The MOTD shows the wrong IP

The login banner captures the public IP at first boot. If you later attach a new Elastic IP / public IP, the banner will be stale (Nexus itself is unaffected). Edit /etc/motd to update it — and on Azure, prefer a static public IP from the start, since every build tool config points at this address.