{inall}
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 exists. 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 {pro} and {oss} support Gem repositories. A user can connect to the repository manager to downloads 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.
|
Important
|
Gem repository support is a feature of version 2.11 and higher, and is available in {pro} and {oss} editions. |
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 gems package and providing them to your users
-
Repository groups for merging multiple hosted and proxy Gem repositories and easily exposing them as one URL to all users
|
Tip
|
None of this functionality requires Ruby (or any extra tooling) to be installed on the operating system running the repository manager. Ruby specific details are implemented using a bundled JRuby. |
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 [confignx-sect-manage-repo]. 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 Proxy Gem Repository Configuration for RubyGems. Further configuration details are available in [confignx-sect-manage-repo].
If you are using {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 [confignx-sect-manage-repo]. A sample configuration for an internal hosted Gem repository is displayed in 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 [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 [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 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 gems repository or better the Gem repository group using the 'Repository Path' 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 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 {nxrm} 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 used 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, as 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