RubyGems Repositories

Introduction

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 via 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 RubyGem 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:

• Proxy repository for connecting to remote gem repositories and caching gems on the repository manager to avoid duplicate downloads and wasted bandwidth and time 
• Hosted repository for hosting gem packages and providing them to users
• Repository groups for merging multiple hosted and proxy gem repositories and easily exposing them as one URL to all users
  
  

Proxying RubyGem Repositories

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, you simply create a new repository using the recipe rubygems (proxy) as documented in Repository Management. 

Minimal configuration steps are:

• Define Name
• Define URL for Remote storage e.g. https://rubygems.org
• Pick a Blob store for Storage

Further configuration details are available in Managing Repositories and Repository Groups.

Private Hosted RubyGem Repositories

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

To create a hosted gem repository, create a new repository using the recipe rubygems (hosted) as documented in Repository Management.

Minimal configuration steps are:

• Define Name
• Select a Blob store for Storage

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

Grouping RubyGem Repositories

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.

To create a gem group repository, create a new repository using the recipe rubygems (group) as documented in Repository Management.

Minimal configuration steps are:

• Define Name
• Select Blob store for Storage
• Add Gems repositories to the Members list in the desired order

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.

Using the repository URL of the repository group as your gem repository URL in your client tool gives you access to the gems in all member repositories with one URL.

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

Using RubyGem Repositories

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/repository/rubygems-group/

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/

Subsequently you should clear the local cache with:

$ gem sources -c 

To check a successful configuration you can run:

$ gem sources
*** CURRENT SOURCES ***


http://localhost:8081/repository/rubygems-group/ 

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

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/repository/rubygems-group/

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/repository/rubygems-group/

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/repository/rubygems-group" 

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.

Pushing Gems

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/repository/rubygems-hosted
The Nexus URL has been stored in ~/.gem/nexus
Enter your Nexus credentials
Username: admin
Password:
Your Nexus credentials has 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/repository/rubygems-hosted