RubyGems Repositories

Proxy a gem repository by creating a new repository using the recipe rubygems (proxy)

Minimal configuration steps are:

A private gem repository can be used as a target to push your 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).

Minimal configuration steps are:

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

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 proxies 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).

Minimal configuration steps are:

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.

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/

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 be downloaded from the repository manager.

If your repository manager requires authentication, you have to add the Basic Auth authentication details to the configuration of the source:

$ 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 the 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.

At this point, you have set up the various gem repositories on the Nexus Repository (proxy, hosted, and group), and are successfully using them for installing new gems on your systems. The 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 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 changing the version for each new deployment instead.

The nexus gem provides several 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