Really simple rubygem hosting
Ruby HTML CSS Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Gem in a Box – Really simple rubygem hosting

Build Status Gem Version Code Climate

Geminabox lets you host your own gems, and push new gems to it just like with The bundler dependencies API is supported out of the box. Authentication is left up to either the web server, or the Rack stack. For basic auth, try Rack::Auth.

screen shot

System Requirements

See .travis.yml for supported ruby versions

Server Setup

gem install geminabox

Create a as follows:

require "rubygems"
require "geminabox" = "/var/geminabox-data" # ... or wherever

# Use Rack::Protection to prevent XSS and CSRF vulnerability if your geminabox server is open public.
# Rack::Protection requires a session middleware, choose your favorite one such as Rack::Session::Memcache.
# This example uses Rack::Session::Pool for simplicity, but please note that:
# 1) Rack::Session::Pool is not available for multiprocess servers such as unicorn
# 2) Rack::Session::Pool causes memory leak (it does not expire stored `@pool` hash)
use Rack::Session::Pool, expire_after: 1000 # sec
use Rack::Protection

run Geminabox::Server

Start your gem server with 'rackup' to run WEBrick or hook up the as you normally would (passenger, thin, unicorn, whatever floats your boat).

Legacy RubyGems index

RubyGems supports generating indexes for the so called legacy versions (< 1.2), and since it is very rare to use such versions nowadays, it can be disabled, thus improving indexing times for large repositories. If it's safe for your application, you can disable support for these legacy versions by adding the following configuration to your file:

Geminabox.build_legacy = false

RubyGems Proxy

Geminabox can be configured to pull gems, it does not currently have, from To enable this mode you can either:

Set RUBYGEM_PROXY to true in the environment:

RUBYGEMS_PROXY=true rackup

Or in (before the run command), set:

Geminabox.rubygems_proxy = true

If you want Geminabox to carry on providing gems when is unavailable, add this to

Geminabox.allow_remote_failure = true

HTTP adapter

Geminabox uses the HTTPClient gem to manage its connections to remote resources. The relationship is managed via Geminabox::HttpClientAdapter.

To configure options of HTTPClient, pass your own HTTPClient object in as:

# Geminabox.http_adapter = # default
Geminabox.http_adapter.http_client =['http_proxy']).tap do |http_client|
  http_client.transparent_gzip_decompression = true
  http_client.keep_alive_timeout = 32 # sec
  http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
  http_client.send_timeout = 0
  http_client.receive_timeout = 0

If you would like to use an alternative HTTP gem, create your own adapter and specify it in

Geminabox.http_adapter =

It is recommend (but not essential) that your adapter inherits from HttpAdapter. The adapter will need to replace HttpAdapter's methods with those specific to the alternative HTTP gem. It should also be able to handle HTTP proxy settings.

Defining your own adapter also allows you to configure Geminabox to use the local systems SSL certificates.

TemplateFaradayAdapter is provided as an example of an alternative HTTPAdapter.


You can add a hook (anything callable) which will be called when a gem is successfully received.

Geminabox.on_gem_received = do |gem|
  puts "Gem received: #{} #{gem.spec.version}"

Typically you might use this to push a notification to your team chat. Any exceptions which occur within the hook is silently ignored, so please ensure they are handled properly if this is not desirable.

Also, please note that this hook blocks POST /upload and POST /api/v1/gems APIs processing. Hook authors are responsible to perform any action non-blocking/async to avoid HTTP timeout.

Client Usage

Since version 0.10, Geminabox supports the standard gemcutter push API:

gem push pkg/my-awesome-gem-1.0.gem --host HOST

You can also use the gem plugin:

gem install geminabox

gem inabox pkg/my-awesome-gem-1.0.gem

Configure Gem in a box (interactive prompt to specify where to upload to):

gem inabox -c

Change the host to upload to:

gem inabox -g HOST


Command Line Help

Usage: gem inabox GEM [options]

    -c, --configure                  Configure GemInABox
    -g, --host HOST                  Host to upload to.
    -o, --overwrite                  Overwrite Gem.

  Common Options:
    -h, --help                       Get help on this command
    -V, --[no-]verbose               Set the verbose level of output
    -q, --quiet                      Silence commands
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

    GEM       built gem to push up

    Push a gem up to your GemInABox

    Push a gem up to your GemInABox


Using Gem in a Box is really simple with the Dockerfile. Move this Dockerfile into a directory that you want to use for your server.

That directory only needs to contain: (explained above)

Your Gemfile only needs:

source ''

gem 'geminabox'

From there

docker build -t geminabox .
docker run -d -p 9292:9292 geminabox:latest

Your server should now be running!