Step-by-Step Guide to Migrating from Nexus 2 to Nexus 3: Tools, Scripts, and Best Practices

Onur Rıdvanoğlu
Dec 3, 2024
3 min read

Updated: Dec 13, 2024

Upgrading from Nexus 2 to Nexus 3 is more than just an improvement—it's a necessity. With Nexus 2 nearing end-of-life, transitioning to version 3 is essential for staying updated and supported. To help you navigate this critical migration, I’ve created a robust set of scripts to ensure a smooth and efficient process.

The main reason I've decided to write this blog is that I struggled to find a viable solution for this migration. While there is official documentation on upgrading the Nexus Repository to version 3, my case was quite different. I needed to merge a Nexus v3 instance and a Nexus v2 instance into a single Nexus Repository. My approach started with creating a new Nexus Repository instance using the latest version via Docker, which was quite easy. Migrating data from the old v3 instance to the new one was quite straightforward. However, the real challenge was transferring data from the v2 instance. That’s when I discovered a repository focused on migrating artifacts from version 2 to 3. I forked the repository and customized it to suit my specific requirements.

And here, I’ll share my own scripts and guide you through how to implement them!

Check out my migration scripts here: nexus-repository-import-scripts.

An illustrative image representing a seamless migration process between two Nexus servers.

Nexus 2 Migration Steps

Step 1: Repository Comparison Utility (compare_nexus_repos.py)

Before migrating repositories, it’s crucial to identify which ones need to be transferred. This Python script helps compare repositories across Nexus 2 and Nexus 3 instances.

Setup

Before running the script, configure your Nexus instances by updating the following section in the script:

# Configure your Nexus instances  
old_nexus = NexusConfig(  
    url="REPO_URL",  # Nexus 2 URL  
    username="username",  # Nexus 2 username  
    password="password",  # Nexus 2 password  
    version=2  
)  

new_nexus = NexusConfig(  
    url="REPO_URL",  # Nexus 3 URL  
    username="username",  # Nexus 3 username  
    password="password",  # Nexus 3 password  
    version=3  
)

Usage

Before running the script make sure that you've connectivity to both of the Nexus instances. Once the configuration is updated, run the script:

python3 compare_nexus_repos.py

Output

The script generates a repository_comparison.json file in your working directory, which highlights repositories unique to each Nexus instance.

This step is essential to identify repositories that need migration and avoid unnecessary work.

Step 2: Artifact Migration Scripts

Once the repositories are identified, the next step is migrating the artifacts. Each migration script must be executed within the specific repository directory on the Nexus 2 machine to ensure correct artifact transfer.

Maven Artifact Uploader (mavenimport.sh)

Efficiently upload Maven Repository artifacts to Nexus 3 repositories.

Key Features:
- Recursively finds and uploads artifacts.
- Avoids pushing artifacts that are already there on the Nexus 3 instance.
- Filters out metadata and system files.
- Tracks successes and failures for detailed reporting.
Usage:

./mavenimport.sh -r https://nexus3.example.com/repository -u admin -p password

NuGet Package Uploader (nugetimport.sh)

NuGet package uploads with automatic discovery of .nupkg files.

Key Features:
- Avoids pushing artifacts that are already there on the Nexus 3 instance.
- Automatically discovers packages within the directory and subdirectories.
- Tracks successes and failures for detailed reporting.
Usage:

./nugetimport.sh -r https://nexus3.example.com/repository -k YOUR_API_KEY

npm Package Uploader (npmimport.sh)

Handles npm package uploads. Please keep in mind that, these scripts avoid pushing artifacts that are already there on the Nexus 3 instance.

Key Features:
- Locates .tgz files and updates publishConfig dynamically (The reason behind this is, in my case, developers had pushed the artifacts with the old nexus repo URL hardcoded inside the package.json file. So I'd to automate the process of changing the URL to the new repo).
- Avoids pushing artifacts that are already there on the Nexus 3 instance.
- Tracks successes and failures for detailed reporting.
Usage:

npm login # Login to your registry first ./npmimport.sh -r https://nexus3.example.com/repository

Why Upgrade?

Migrating to Nexus 3 ensures:

Access to New Features: Enhanced performance, better UI, and advanced capabilities.
Continued Support: Nexus 2 is nearing end-of-life, and support will soon be discontinued.
Improved Security: Nexus 3 offers better security features and regular updates.

Conclusion

Migrating from Nexus 2 to Nexus 3 may seem daunting, but with these scripts, you can make the process seamless and efficient. Remember to:

Start with Repository Comparison: Identify what needs to be migrated.
Run Scripts Inside Nexus 2 Repository Directories: This ensures artifacts are correctly located and transferred.
Test in Staging First: Always verify the migration in a non-production environment before going live.

You can find the complete scripts and detailed documentation here: nexus-repository-import-scripts.

Happy Migrating! 🚀