Skip to main content

Support

Use this page to find operational guidance for common migration scenarios. It brings together FAQs and advanced workflow examples so you can diagnose problems, understand migrator behaviour and apply the right migration approach for your environment.

Advanced Workflow Examples

Scenario 1: Selective Repository Migration with Filtering

Goal: Migrate only specific repositories from a large Nexus instance

# Step 1: Start interactive shell
java -jar nexus-repository-instance-migrator-1.0.0-SNAPSHOT.jar

# Step 2: Configure connections
nx-migration:> config set source-nexus-url http://localhost:8081
nx-migration:> config set source-nexus-username admin
nx-migration:> config set source-nexus-password admin123
nx-migration:> config set target-nexus-url https://cloud.example.com
nx-migration:> config set target-nexus-username clouduser
nx-migration:> config set target-nexus-password cloudpass123

# Step 3: Read all configuration (creates repository mappings)
nx-migration:> migrate-config-read

# Step 4: Set filter to migrate only specific repositories
nx-migration:> config set override-repositories maven-central,npm-proxy,docker-hub

# Step 5: Verify connections
nx-migration:> status

# Step 6: Write filtered configuration to target
nx-migration:> migrate-config-write

# Step 7: Migrate content for filtered repositories only
nx-migration:> migrate-content
# This will migrate: maven-central, npm-proxy, docker-hub (using their target mappings)

Scenario 2: Single Repository Migration with Custom Target

Goal: Migrate one repository to a differently named target repository

# Using the interactive shell with explicit repository mapping
nx-migration:> migrate-content --source-repository old-maven-repo --target-repository new-maven-repo

Scenario 3: Configuration-Driven Bulk Migration

Goal: Use configuration file mappings to migrate multiple repositories automatically

# Step 1: Read source configuration (creates mappings file)
nx-migration:> migrate-config-read

# Step 2: Migrate all repositories using configuration mappings
nx-migration:> migrate-content
# This reads the configuration file and migrates ALL repositories found
# Each repository uses its targetRepositoryName from the configuration

Scenario 4: Development to Production Migration

Goal: Migrate from development to production with repository renaming

# Configuration shows dev repositories need prod suffixes
# config file contains mappings like:
# "repositoryName": "maven-central-dev" -> "targetRepositoryName": "maven-central-prod"

# Step 1: Configure for dev->prod migration
nx-migration:> config set source-nexus-url http://dev-nexus:8081
nx-migration:> config set target-nexus-url http://prod-nexus:8081

# Step 2: Read dev configuration
nx-migration:> migrate-config-read

# Step 3: Apply configuration to production (with name mappings)
nx-migration:> migrate-config-write

# Step 4: Migrate content using mapped names
nx-migration:> migrate-content
# maven-central-dev -> maven-central-prod
# npm-proxy-dev -> npm-proxy-prod
# etc.

Scenario 5: Incremental Migration with Filtering

Goal: Migrate repositories in batches.

# Batch 1: Critical repositories
nx-migration:> config set override-repositories maven-central,releases,snapshots
nx-migration:> migrate-content

# Batch 2: Secondary repositories  
nx-migration:> config set override-repositories npm-proxy,docker-hub,pypi-proxy
nx-migration:> migrate-content

# Batch 3: All remaining repositories
nx-migration:> config set override-repositories ""  # Clear filter
nx-migration:> migrate-content  # Migrates any remaining repositories

Scenario 6: Pre-Configured Shell with Environment Variables

Goal: Launch the shell with pre-configured settings for quick migration.

# Pre-configure via environment variables
export SOURCE_NEXUS_URL=http://localhost:8081
export SOURCE_NEXUS_USERNAME=admin
export SOURCE_NEXUS_PASSWORD=admin123
export CONFIGURATION_JSON=migration-config.json

# Launch shell with settings already configured
java -jar nexus-repository-instance-migrator-1.0.0-SNAPSHOT.jar
nx-migration:> migrate-config-read  # Uses environment variables
nx-migration:> config show  # Review pre-configured settings
nx-migration:> config set override-repositories critical-repo1,critical-repo2
nx-migration:> migrate-content  # Migrate only critical repositories first

Frequently Asked Questions

  • How do I fix connection timeouts?

    Increase the connection-timeout-ms and read-timeout-ms values to give the migrator more time to connect and read responses from the source or target instance.

  • What should I check for version compatibility issues?

    Ensure that both Nexus instances are running compatible versions before you start the migration.

  • What should I do if I run into memory issues during migration?

    Increase the JVM heap size, for example by using -Xmx2g, for large migrations.

  • What should I check if I suspect a network issue?

    Verify firewall settings and confirm network connectivity between the migrator and both Nexus instances.

  • What should I do if there are state file issues?

    Check the state/ directory permissions and available disk space to make sure state can be persisted correctly.

  • Why is polling mode not starting?

    Verify that the source repositories exist and are accessible before you start polling mode.

  • What should I do if migration resume is not working correctly?

    Clear the state files in the state/ directory to restart the migration from the beginning.

  • What should I do if the migrator cannot write log files?

    Ensure that the logs/ directory is writable for both transfer logs and application logs.

  • How do I troubleshoot general connection issues?

    Start the migrator and run the status command to check connectivity.

    java -jar nexus-repository-instance-migrator-1.0.0-SNAPSHOT.jar
status

  • How do I troubleshoot configuration issues?

    Use config show to review the current configuration, then use config set to provide any missing values.

    config show
config set source-nexus-url http://localhost:8081

  • What should I check if authentication fails?

    Verify that the credentials are correct, confirm that the source and target instances are accessible, ensure network connectivity and firewall settings are correct, and verify that the user has administrator privileges.

  • How do I troubleshoot performance issues?

    Adjust the --connection-timeout-ms and --read-timeout-ms settings, monitor the log files for detailed error information, and use the DEBUG logging level for deeper troubleshooting.

  • How long does migration take?

    Migration time depends on data volume. Configuration-only migrations typically take 1-5 minutes. Small installations under 100 GB typically take 1-4 hours. Medium installations from 100-500 GB typically take 4-24 hours. Large installations over 500 GB typically take 1-7 days.

  • What happens to Docker image layers?

    Docker layers are migrated along with other assets. Docker manifests and tags are preserved.

  • Are audit logs migrated?

    No. Audit logs remain on the source instance. Archive them separately before decommissioning the source.

  • Do users need to re-authenticate after migration?

    Local users do not need to re-authenticate because passwords are preserved when the cipher is configured. LDAP, SAML, and Crowd users do need to re-authenticate because external role memberships are not migrated. Users must re-authenticate after LDAP or SAML is configured on the target.

  • What about Pro features (IQ Server, Firewall)?

    Pro plugin configurations such as IQ Server, Firewall, and Lifecycle are exported as capabilities. Ensure the target instance has a valid Pro license and the same plugins installed.

  • Can I migrate specific repositories only?

    Yes. Use the override-repositories setting in the migrator to specify which repositories to migrate.

Logging and Debugging FAQs

  • What is the successful asset transfer log used for?

    The successful asset transfer log provides an audit trail of all successfully migrated assets. Use it to verify which assets have been migrated and to track migration progress. The application also uses this log to resume or verify partial migrations.

    Log file: logs/asset-transfers.log

    Format: timestamp repository-name - asset-path

    2025-11-0410:15:23.456maven-central-/com/example/artifact/1.0.0/artifact-1.0.0.jar
2025-11-0410:15:24.123npm-proxy-/@babel/core/-/core-7.23.0.tgz

  • What is the failed asset transfer log used for?

    The failed asset transfer log helps track and diagnose asset transfer failures. Use it to identify problematic assets, troubleshoot migration issues, and investigate possible data integrity problems.

    Log file: logs/failed-asset-transfers.log

    Format: timestamp repository-name - asset-path - failure-reason

    2025-11-0410:15:25.789maven-central-/com/example/bad/1.0.0/bad-1.0.0.jar -Checksum mismatch-source:{sha1=abc123} target:{sha1=def456}
2025-11-0410:15:26.234npm-proxy-/package.tgz -Download failed -null response from source Nexus

  • How do I enable debug logging?

    Use the DEBUG logging level for com.sonatype.nexus.tools.

    --logging.level.com.sonatype.nexus.tools=DEBUG

  • How do I change the log file location?

    Set a custom value for logging.file.name.

    --logging.file.name=/path/to/custom/logfile.log

  • How do I use console-only logging?

    Set logging.file.name to an empty string to disable file logging and use console-only output.

    --logging.file.name=""

  • How do I configure log rotation?

    Use logging.file.max-size and logging.file.max-history to control file rotation behavior.

    --logging.file.max-size=10MB
--logging.file.max-history=30

Getting Help FAQs

  • How do I get help in interactive shell mode?

    Use help for built-in shell commands and migrate-help for migration-specific commands.

    help               # Built-in shell commands
migrate-help       # Migration-specific commands