Ruby, RubyGems and Gem Repositories in Nexus Repository 2

For developers using the Ruby programming language, the gem tool serves as their package management solution. In fact, since version 1.9 of Ruby, it has been included as part of the default Ruby library. Packages are called gems and, just like all package managers, this allows for ease of use when distributing programs or libraries.

Of course, package management really only goes as far as improving distribution. A great feat certainly, but to really find success, a development community needs to exist. At the heart of every development community, especially those like Ruby, where open source projects are one of the most critical elements, the community needs a place to host and share their projects.

Enter RubyGems hosted at rubygems.org - the most popular and leading gem hosting service supporting the Ruby community. Here, a large variety of open source Ruby projects supply their gems for download to all users.

Ruby has been a successful platform for developers for a long time now. The popularity of Ruby and therefore the usage of gems and gem repositories means that lots of teams are downloading and exchanging lots of components on a regular basis. Obviously, this can (and does) become a crunch on resources, not to mention a pain to manage.

Luckily Nexus Repository Manager Pro and Nexus Repository Manager OSS support gem repositories. A user can connect to the repository manager to download gems from RubyGems, create proxies to other repositories, and host their own or third-party gems. Any gem downloaded via the repository manager needs to be downloaded from the remote repository, like RubyGems, only once and is then

available internally from the repository manager. Gems pushed to the repository manager automatically become available to everyone else in your organization. Using the repository manager as a proxy avoids the overhead of teams and individual developers having to repeatedly download components or share components in a haphazard and disorganized manner.

The following features are included as part of the gem repository support:

To reduce duplicate downloads and improve download speeds for your developers, continuous integration servers and other systems using gem, you should proxy the RubyGems repository and any other repositories you require.

To proxy an external Gem repository, like RubyGems, simply create a new Proxy Repository as documented in Managing Repositories. The Provider has to be set to Rubygems. The Remote Storage Location has to be set to the URL of the remote repository you want to proxy. The official URL for Rubygems.org is

https://rubygems.org

This main configuration for proxying RubyGems is visible in Figure 17.1, “Proxy Gem Repository Configuration for RubyGems”. Further configuration details are available in Managing Repositories.

Figure 17.1. Proxy Gem Repository Configuration for RubyGems

If you are using Nexus Repository Manager Pro and are proxying a repository via HTTPS, you can get the certificate added to the repository manager truststore to simplify management using the SSL tab of the repository configuration.

Scheduled tasks can be used to purge broken metadata of a proxy gem repository as well as to synchronize the metadata files of a proxy gem repository.

A private Gem repository on repository manager can be used as target to push your own gems as well as third-party gems and subsequently provide them to your users. It is good practice to create two separate hosted Gem repositories for internal and third-party gems.

To create a hosted Gem repository, simply create a new Hosted Repository and set the Provider to Rubygems as documented in Managing Repositories. A sample configuration for an internal hosted Gem repository is displayed in Figure 17.2, “Example Configuration for a Private Gem Repository”.

Figure 17.2. Example Configuration for a Private Gem Repository

The Gem repository information is immediately updated as gems are pushed to the repository or deleted from it.

A scheduled task can be used to rebuild the metadata of a hosted gem repository and can be configured as documented in Managing Scheduled Tasks.

A repository group is the recommended way to expose all your Gem repositories to your users, without needing any further client side configuration after initial setup. A repository group allows you to expose the aggregated content of multiple proxy and hosted Gem repositories with one URL to gem and other tools. This is possible for Gem repositories by creating a new Repository Group with the Provider set to Rubygems as documented in Managing Repository Groups.

A typical, useful example would be to group the proxy repository that proxies the RubyGems repository, a hosted Gem repository with internal software gems, and another hosted Gem repository with third-party gems. The configuration for such a setup is displayed in Figure 17.3, “A Gem Repository Group Combining the RubyGems Proxy Repository and Two Private Gem Repositories”.

Figure 17.3. A Gem Repository Group Combining the RubyGems Proxy Repository

and Two Private Gem Repositories

Using the Repository Path of the repository group as your Gem repository URL in your client tool gives you access to the gems in all three repositories with one URL.

Any new gem added to the remote proxy Gem repositories or the hosted Gem repositories becomes immediately available to all users of the Gem repository group. Adding a new proxy Gem repository to the group makes all gems immediately available to the users as well.

Once you have configured the repository manager with the gem repository group, you can add it to your configuration for the gem command line tool.

You can add the URL of a gem repository or group using the URL from the repository list with a command like

gem sources --add http://localhost:8081/nexus/content/groups/gems-all/

In order to take full advantage of the repository manager and the proxying of gems, you should remove any other sources. By default https://rubygems.org/ is configured in gem and this can be removed with

$ gem sources --remove https://rubygems.org/
https://rubygems.org/ removed from sources

Subsequently you should clear the local cache with

$ gem sources -c
*** Removed specs cache ***

To check a successful configuration you can run

$ gem sources
*** CURRENT SOURCES ***

http://localhost:8081/nexus/content/groups/gems-all/

With this setup completed any installation of new gems with gem install GEMNAME (e.g. gem install rake) will download from the repository manager.

By default read access is available to anonymous access and no further configuration is necessary. If your repository manager requires authentication, you have to add the Basic Auth authentication details to the sources configuration:

$ gem sources --add
http://myuser:mypassword@localhost:8081/nexus/content/repositories/gems-all/

If you are using the popular Bundler tool for tracking and installing gems, you need to install it with gem:

$ gem install bundle
Fetching: bundler-1.7.7.gem (100%)
Successfully installed bundler-1.7.7
Fetching: bundle-0.0.1.gem (100%)
Successfully installed bundle-0.0.1
Parsing documentation for bundle-0.0.1
Installing ri documentation for bundle-0.0.1
Parsing documentation for bundler-1.7.7
Installing ri documentation for bundler-1.7.7
Done installing documentation for bundle, bundler after 4 seconds
2 gems installed

To use the repository manager with Bundler, you have to configure the gem repository group as a mirror:

$ bundle config mirror.http://rubygems.org
http://localhost:8081/nexus/content/repositories/gems-all

You can confirm the configuration succeeded by checking the configuration:

$ bundle config
Settings are listed in order of priority.
The top value will be used.
mirror.http://rubygems.org
Set for the current user (/Users/manfred/.bundle/config):
"http://localhost:8081/nexus/content/repositories/gems-all"

With this configuration completed, you can create a Gemfile and run bundle install as usual and any downloads of gem files will be using the gem repository group configured as a mirror.

At this point you have set up the various gem repositories on the repository manager (proxy, hosted and group), and are successfully using them for installing new gems on your systems. A next step can be to push gems to hosted gem repositories to provide them to other users. All this can be achieved on the command line with the features of the nexus gem.

The nexus gem is available at RubyGems and provides features to interact with Nexus Repository Manager Pro including pushing gems to a hosted gem repository including the necessary authentication.

You can install the nexus gem with

$ gem install nexus
Fetching: nexus-1.2.1.gem (100%)
...
Successfully installed nexus-1.2.1
Parsing documentation for nexus-1.2.1
Installing ri documentation for nexus-1.2.1
Done installing

After successful installation you can push your gem to a desired repository. The initial invocation will request the URL for the gem repository and the credentials needed for deployment. Subsequent pushes will use the cached information.

$gem nexus example-1.0.0.gem
Enter the URL of the rubygems repository on a Nexus server
URL:   http://localhost:8081/nexus/content/repositories/gems-internal
The Nexus URL has been stored in ~/.gem/nexus
Enter your Nexus credentials
Username:   admin
Password:
Your Nexus credentials have been stored in /Users/manfred/.gem/nexus
Uploading gem to Nexus...
Created

By default pushing an identical version to the repository, known as redeployment, is not allowed in a hosted gem repository. If desired this configuration can be changed, although we suggest to change the version for each new deployment instead.

The nexus gem provides a number of additional features and parameters. You can access the documentation with

$ gem help nexus 

E.g. you can access a list of all configured repositories with

$gem nexus --all-repos

DEFAULT:
http://localhost:8081/nexus/content/repositories/gems-internal