Skip to end of metadata
Go to start of metadata

Nexus Repository Conversion Tool

Introduction

If you are trying to import a repository that contains both SNAPSHOTs and Release artifacts, or a local repository into Nexus, this tool can help. It is used to convert a mixed maven repository to 2 separate maven repositories, one for releases and the other for snapshots. It is able to work on remote or local repository layouts. The theory of operation is fairly simple, it analyzes each folder and determines if it is a SNAPSHOT or Release and places it in the correct location. All maven-metadata.xml is dumped and will be rebuilt by Nexus once everything is sorted out. It is the metadata only that distringuishes a local from a remote repository layout.

Download

You may download the release and snapshot version of this tool from http://repository.sonatype.org/content/groups/public/org/sonatype/nexus/tools/nexus-repository-conversion-tool/

Notice that the file with name ending with "-cli.jar" is the executable application. Download it and put it in any place you want.

Run

Run it using java -jar.  For example, if I downloaded the version 1.7.2 (nexus-repository-conversion-tool-1.7.2-cli.jar), then run java -jar  nexus-repository-conversion-tool-1.7.2-cli.jar -h, you'll see the following output:

usage: java -jar cli-jar-name [options]

Options:
 -q,--quiet         Quiet output - only show errors
 -D,--define        Define a system property
 -X,--debug         Produce execution debug output
 -e,--errors        Produce execution error messages
 -h,--help          Display help information
 -m,--move          Move the repository (old repository will be deleted ).
 -o,--output        Where the converted repositoris locate.
 -r,--repository    The repository to be converted.
 -v,--version       Display version information

Note that '-r' stands for the mixed repository we want to convert, and the option '-o' stands for the output directory the converted repositories will be placed into. If our mixed repository's directory is /home/juven/mixed_repo, and we want to convert it to /home/juven/output_repos/, we should run this tool like this:

 java -jar  nexus-repository-conversion-tool-1.7.2-cli.jar -r/home/juven/mixed_repo/ -o/home/juven/output_repos/

If everything is ok, you'll see output saying "Repository conversion is successful!" , and check the directory /home/juven/output_repos/, there are now 2 sub-directories mixed_repo_releases and mixed_repo_snapshots. So now the mixed repository is converted to 2 separated repositories.

Other Options

If you want the old mixed repository be removed automatically after the conversion, simply add a '-m' option. This means move the repo so the old one will be deleted. Notice that by default we keep the old mixed repository in place as a backup.

Import into Nexus

Now that you have the separated repository, importing the data into Nexus is easy.In the UI create the two hosted repositories you want to hold this data, one for snapshots and one for releases.

Then locate your sonatype-work folder on the Nexus server. By default it will be in ../sonatype-work (a sibling folder of the Nexus application) for the bundle, and in ~/sonatype-work if you used the war. Copy or Move the contents of the repositories into sonatype-work/storage/[NX:repository id] using the correct repository id's you just created. Don't forget to add these new repositories to a group and adjust any routing rules that you may have.

Then in the UI, navigate to the Browse Repository view, right click on each repository and run rebuild Maven Metadata and then Re-index. Once those tasks are complete, your import is done. (Once the Maven Metadata tasks are done, Maven will be able to access the files just fine...the Re-index is for searching or browsing via M2eclipse)

Nexus Preparation Tool

Introduction

The Nexus Preparation Tool is a command line tool used to prepare nexus configuration for the to-be-hosted oss projects.

Based on the necessary information you provided for a oss project, nexus repositories, groups, repository targets, privileges, roles, staging profiles and users will be created correspondingly.

Download

This tool can be downloaded from http://repository.sonatype.org/content/groups/public/org/sonatype/community/community-nexus-preparation-tool/, notice that you need to use the files ending with '-cli.jar'.

You can also check out the source code and build locally.
Check out the source code from https://svn.sonatype.com/repos/code/nexus-community-work/trunk/community-aggregator/.
Build the project, then go to /community-aggregator/community-nexus-preparation-tool/target/, the file ends with -cli.jar is what we want.

Run

Use the help option to know how to use this tool: java -jar community-nexus-preparation-tool-1.3.3-SNAPSHOT-cli.jar -h, you will see:

usage: java -jar cli-jar-name preparation-configuration-file [NX:options]

Options:
 q,-quiet     Quiet output - only show errors
 D,-define    Define a system property
 X,-debug     Produce execution debug output
 e,-errors    Produce execution error messages
 h,-help      Display help information
 v,-version   Display version information

So you need to provide a preparation-configuration-file to tell this tool what to prepare,  the configuration file is a simple properties file like this:

base-url=http://oss.sonatype.org/
nexus-username=***
nexus-password=***

project-id=maven-overview-plugin
group-id=com.googlecode.maven-overview-plugin
parent-project-id=googlecode

target-pattern=./com/googlecode/maven-overview-plugin/.* ./com/google/code/maven-overview-plugin/.*

user.foo=Foo F|foo@sonatype.com
user.bar=Bar B|bar@sonatype.com

Here we must provide these information:

  • Base URL of the nexus instance, the administrator user id and password used to login.
  • The project id and group id of the oss project, all the stuff created in nexus will be mainly named based on these ids.
  • (Optional) The parent project id: if multiple oss projects' group id share the same beginning, (eg: com.googlecode.maven-overview-plugin and com.googlecode.mvndroid) they should share a same parent repository as well.
  • Target Pattern: The privileges of this project's user are controled by the target patterns. You can specify more than one patterns, seprated by a blank space.
  • User: These nexus users will be created so that they can do deployment and staging work on the nexus instance, they can also login to nexus and change their password (The default password is 'admin123'). Here we configured 2 users, the first user has a id of 'foo', name of 'Foo F' and email of 'foo@sonatype.com'.  The format is 'user.<id>=<name>|<email>'.

Now run the tool:

juven@juven-ubuntu:test$ java -jar community-nexus-preparation-tool-1.3.3-SNAPSHOT-cli.jar prep-maven-overview-plugin.properties
-- Start to prepare nexus repository. --
[NX:INFO] Repository Target 'com.googlecode.maven-overview-plugin' is created.
[NX:INFO] Repository 'googlecode-snapshots' is created.
[NX:INFO] Repository 'googlecode-releases' is created.
[NX:INFO] Reporitory Group 'googlecode' is created.
[NX:INFO] Reporitory Group 'googlecode-with-staging' is created.
[NX:INFO] Staging Profile 'com.googlecode.maven-overview-plugin' is created.
[NX:INFO] Privileges 'com.googlecode.maven-overview-plugin - Googlecode Repositories' are created.
[NX:INFO] Privileges 'com.googlecode.maven-overview-plugin - Googlecode With Staging' are created.
[NX:INFO] Role 'com.googlecode.maven-overview-plugin Deployment Role' is created.
[NX:INFO] User 'Foo F' is created.
[NX:INFO] User 'Bar b' is created.
-- Nexus repository was prepared successfully. --

Here are the results:

  1. Repository Target: Named by its group-id, containing the specified target patterns.
  2. Repositories: Named by its project-id (or parent-project-id, if specified), one for release artifacts and the other for snapshot artifacts. Note that if the parent-project repositories is already existent, the tool won't create new repositories.
  3. Repository Groups: Named by its project-id (or parent-project-id, if specified), one for common usage and the other is for staging (is the target group of staging profile). Both contains the repositores created in the previous step.
  4. Staging Profile: Named by its group-id, will use the staging group just created as its target group, will use repositories just created as its repository target.
  5. Privileges: Named by repository target id and repository groups' name, including CRUD permissions for all the created repository groups, but limited to its repository target.
  6. Role: Named by group-id, containing all the privileges just created, the privileges/roles related to the staging profile just created, and basic-ui, anonymous, all-repo-read roles.
  7. Users: Id, name and email are specified in the properties file, the default passwod is 'admin123', all the users contains the role just created.

So, the result ism the use project-id-deployer can:

  • login: use the id specified and default password
  • change his password
  • browse all repositories
  • deploy to his repositories: base-url/content/repositories/project-id-releases/, base-url/content/repositories/project-id-snapshots/
  • maintain his staging profile
  • deploy to staging repository: base-url/service/local/staging/deploy/maven2/
  • do staging operations: finish, drop, promote

Security Import Tool

Introduction

This tool is used to import security groups from ini file into Nexus. Groups in ini file will become roles in nexus, and user-role mapping will be created (or updated) in Nexus, corresponding to the group-user configurations in ini file.

Download

You can download this tool from: http://repository.sonatype.org/content/groups/sonatype-grid/com/sonatype/community/community-security-import-tool/1.0-SNAPSHOT/ , note that you need to use the files ending with '-cli.jar'.

You can also check out the source code and build locally.
Check out the source code from https://svn.sonatype.com/repos/code/nexus-community-work/trunk/community-aggregator/.
Build the project, then go to /community-aggregator/community-security-import-tool/target/, the file ends with -cli.jar is what we want.

Run

First you can run the tool with help option enabled: java -jar community-security-import-tool-1.0-SNAPSHOT-cli.jar -h, you will see:

usage: java -jar cli-jar-name [options] [group [group2] [group3] ...]

Options:
 -q,--quiet                Quiet output - only show errors
 -brole <base-role>        the base role of all to-be imported roles
 -D,--define               Define a system property
 -X,--debug                Produce execution debug output
 -base <baseUrl>           the base url of nexus
 -e,--errors               Produce execution error messages
 -h,--help                 Display help information
 -ini <iniFilePath>        the path of the ini file
 -pwd <password>           the password used to login nexus
 -realm <security-realm>   the security realm used by Nexus server
 -uname <username>         the username used to login nexus
 -v,--version              Display version information

As the help message says, you must provide the following parameters:

  • The path of the ini file.
  • The base url of nexus.
  • The username and password used to log in nexus.
  • The base role of all to-be imported roles. (In another word, all imported roles will contain this base role)
  • The security realm nexus is using
  • One or more groups you want to import. (The group should be configured in your ini file)
    Here is a sample ini file:
    [groups]
    asia=china,japan,korea
    europe=england,hungary,france,russia
    america=usa
    
    Now we want to import group asia and europe into nexus, so run: java -jar community-security-import-tool-1.0-SNAPSHOT-cli.jar -ini test-group.ini -base http://localhost:8081/nexus -uname admin -pwd admin123 -brole earth-base -realm ldap asia europe
    If everything goes well, you will some output like this:
    -- Start to import security data. --
    [INFO] Loading group and user data...
    [INFO] Adding role and user-role mapping data into Nexus...
    [INFO] Role with ID = 'earth-base' is created.
    [INFO] Role with ID = 'asia' is created.
    [INFO] User-Role mapping with userId = 'china' is created for role 'asia'.
    [INFO] User-Role mapping with userId = 'japan' is created for role 'asia'.
    [INFO] User-Role mapping with userId = 'korea' is created for role 'asia'.
    [INFO] Loading group and user data...
    [INFO] Adding role and user-role mapping data into Nexus...
    [INFO] Role with ID = 'asf-anon' is already existed, won't create a new one.
    [INFO] Role with ID = 'europe' is created.
    [INFO] User-Role mapping with userId = 'england' is created for role 'europe'.
    [INFO] User-Role mapping with userId = 'france' is created for role 'europe'.
    [INFO] User-Role mapping with userId = 'hungary' is created for role 'europe'.
    [INFO] User-Role mapping with userId = 'russia' is created for role 'europe'.
    -- Security data was imported successfully. --
    
    You will see role 'earth-base' is created, this role is the base role of all other imported roles.
    Role 'asia' and 'europe' are created, they are actually groups we imported.
    User-Role mappings are created for each user listed after the the group.
Others
  1. you must have some security realm installed on you nexus before running this tool
  2. this tool is tested on nexus 1.4-SNAPSHOT