Packagecloud logo

HOWTO: Set up a private gem server


This post covers how to run a simple gem server to host your ruby gems. If you require the ability to push packages and host them, you can use something like the Gem in a Box Project. is a hosted solution which allows you to push, host and manage gems in a secure package repository.



There are many reasons to host your own gem server. It could be to easily host packages offline for development purposes, to ensure the security of intellectual property over a trusted network or to remove a dependency on a third-party service (like when deploying software.

Whatever your specific case calls for, running a gem server doesn’t come without some technical overhead. This post will try to outline some ways to help you manage your gem installation and distribution requirements.

Local Gem Servers

Using RubyGems Default Server

RubyGems is bundled with a command - aptly named gem server - used for serving installed rubygems.

$ gem server
  Server started at

The gem server command starts a server on a port (default is 8808 - can be specified with -p or --port) and will, by default, serve up all packages installed on the local system. You can visit http://localhost:8808 in a browser to see an index of all the packages installed on the system.

In order to use the local gem server as a source for installing gems, you must ensure that the cache files for the gems exist on the system running the server. You can also specify a directory (or directories) to search for installed gems by passing the -d or --dir options to the gem server command.

$ gem server -d /path/to/your/gems

To make new packages available, just add the desired gems into the specified gem directory.

To see all available options, run:

$ gem server --help


Using Gem in a Box

If you need to be able to push gems, as well as host them, take a look at the Gem in a Box Project. geminabox allows you to push gems and host them from your local machine.

First, install geminabox:

$ gem install geminabox

As per the project README, create a with the following:

require "rubygems"
require "geminabox" = "/path/to/your/gem/repo"
run Geminabox::Server

Next, make sure the /path/to/your/gem/repo folder exists. This is where your packages will end up when pushing them via the geminabox command.

$ mkdir /path/to/your/gem/repo

Then, run the server from your

[~/geminabox-server] rackup
Thin web server (v1.6.1 codename Death Proof)
Maximum connections set to 1024
Listening on localhost:9292, CTRL+C to stop

Once the server is up and running, you can push packages using the command-line utility gem inabox

$ gem inabox /path/to/file.gem

Or visit the page http://localhost:9292 in a browser and use the web-upload function provided by the geminabox server. This page also lists all the packages pushed to your geminabox server.


Hosted Gem Server

Using as a hosted gem server provides pubic and private package repositories that you can use to host rubygems, debian and redhat packages. To start using packagecloud as a gem server, first create an account and repository on

Once you have an account, a repository can be created by either using the web interface or by using the cli.

After creating a repo, install the gem:

$ gem install package_cloud

Next, push your gem file to your newly created repo:

$ package_cloud push user/repo /path/to/file.gem
No config file exists at /path/to/.packagecloud. Login to create one.
Looking for repository at user/repo... success!
Pushing /path/to/file.gem... success!

When running the push command for the first time, you will be prompted to enter your email address and password for the site.


Installing gems from your gem server

To install packages from your gem server of choice (, geminabox or gem server), you must set the source for gems on your system. This can be done by using the gem sources command and passing it the path to your server:

$ gem sources --add

Then install gems as you normally would:

$ gem install private-gem

Or if you’re using Bundler, set the source in the Gemfile directly:

source ""
gem "private-gem"


Using your own gem server has many advantages, such as decoupling your deployment process from a third-party service like and protecting private libraries from being shared over the internet. Taking granular control of your packaging system gives you the advantage of ensuring your packages are available when you need them and are accessible in a safe and secure way.

For a more full-featured setup including a token-authentication system, automation tooling and a robust API, makes it easy to create and manage package repositories for ruby gems.

You might also like other posts...