gemstash 2.0.0 → 2.1.0

data/lib/gemstash/man/gemstash-mirror.7

@@ -0,0 +1,40 @@
+.\" Automatically generated by Pandoc 2.5
+.\"
+.TH "gemstash\-mirror" "7" "October 25, 2015" "" ""
+.hy
+.SH USING GEMSTASH AS A MIRROR
+.PP
+If you don\[cq]t have control over your \f[C]Gemfile\f[R], or you
+don\[cq]t want to force everyone on your team to go through the Gemstash
+server, you can use Bundler mirroring to bundle against your Gemstash
+server.
+.PP
+For each source in your \f[C]Gemfile\f[R], add a mirror pointing to your
+Gemstash server:
+.IP
+.nf
+\f[C]
+$ bundle config mirror.http://rubygems.org http://localhost:9292
+$ bundle config mirror.https://my.gem\-source.local http://localhost:9292/upstream/$(ruby \-rcgi \-e \[aq]puts CGI.escape(\[dq]https://my.gem\-source.local\[dq])\[aq])
+\f[R]
+.fi
+.PP
+From now on, bundler will fetch gems from those sources via your
+Gemstash server.
+.SH SIMPLER GEMSTASH MIRRORS
+.PP
+\f[B]This feature requires Bundler to be at least version
+\f[CB]1.11.0\f[B].\f[R]
+.PP
+If you are using Bundler version \f[C]1.11.0\f[R] or greater, the
+mirroring becomes a bit easier:
+.IP
+.nf
+\f[C]
+$ bundle config mirror.http://rubygems.org http://localhost:9292
+$ bundle config mirror.https://my.gem\-source.local http://localhost:9292
+\f[R]
+.fi
+.PP
+Bundler will then send headers to Gemstash to indicate the correct
+upstream.

data/lib/gemstash/man/gemstash-mirror.7.txt

@@ -1,66 +1,33 @@
+gemstash-mirror(7)					    gemstash-mirror(7)
 
 
 
+1mUSING GEMSTASH AS A MIRROR0m
+       If you don't have control over your Gemfile, or you don't want to force
+       everyone on your team to go through the Gemstash server,	 you  can  use
+       Bundler mirroring to bundle against your Gemstash server.
 
+       For each source in your Gemfile, add a mirror pointing to your Gemstash
+       server:
 
+	      $ bundle config mirror.http://rubygems.org http://localhost:9292
+	      $ bundle config mirror.https://my.gem-source.local http://localhost:9292/upstream/$(ruby -rcgi -e 'puts CGI.escape("https://my.gem-source.local")')
 
+       From now on, bundler will fetch gems from those sources via  your  Gem-
+       stash server.
 
+1mSIMPLER GEMSTASH MIRRORS0m
+       1mThis feature requires Bundler to be at least version 1.11.0.0m
 
+       If  you	are using Bundler version 1.11.0 or greater, the mirroring be-
+       comes a bit easier:
 
+	      $ bundle config mirror.http://rubygems.org http://localhost:9292
+	      $ bundle config mirror.https://my.gem-source.local http://localhost:9292
 
+       Bundler will then send headers to Gemstash to indicate the correct  up-
+       stream.
 
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+			       October 25, 2015		    gemstash-mirror(7)

data/lib/gemstash/man/gemstash-multiple-sources.7

@@ -0,0 +1,89 @@
+.\" Automatically generated by Pandoc 2.5
+.\"
+.TH "gemstash\-multiple\-sources" "7" "October 8, 2015" "" ""
+.hy
+.SH MULTIPLE GEM SOURCES
+.PP
+Gemstash will stash from any amount of gem sources.
+By the end of this guide, you will be able to bundle using multiple gem
+sources, all stashed within your Gemstash server.
+.SS DEFAULT SOURCE
+.PP
+When you don\[cq]t provide an explicit source (as with the Quickstart
+Guide (../readme.md#quickstart-guide)), your gems will be fetched from
+https://rubygems.org.
+This default source is not set in stone.
+To change it, you need only edit the Gemstash configuration found at
+\f[C]\[ti]/.gemstash/config.yml\f[R]:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+\-\-\-
+:rubygems_url: https://my.gem\-source.local
+\f[R]
+.fi
+.PP
+Make sure to restart your Gemstash server after changing the config:
+.IP
+.nf
+\f[C]
+$ gemstash stop
+$ gemstash start
+\f[R]
+.fi
+.PP
+Once restarted, bundling against \f[C]http://localhost:9292\f[R] will
+fetch gems from \f[C]https://my.gem\-source.local\f[R].
+If you had bundled before making these changes, fear not; bundling with
+a different default gem source will store gems in a separate location,
+ensuring different sources won\[cq]t leak between each other.
+.SS BUNDLING WITH MULTIPLE SOURCES
+.PP
+Changing the default source won\[cq]t help you if you need to bundle
+against https://rubygems.org along with additional sources.
+If you need to bundle with multiple gem sources, Gemstash doesn\[cq]t
+need to be specially configured.
+Your Gemstash server will honor any gem source specified via a
+specialized URL.
+Consider the following \f[C]Gemfile\f[R]:
+.IP
+.nf
+\f[C]
+# ./Gemfile
+require \[dq]cgi\[dq]
+source \[dq]http://localhost:9292\[dq]
+gem \[dq]rubywarrior\[dq]
+
+source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]https://my.gem\-source.local\[dq])}\[dq] do
+  gem \[dq]my\-gem\[dq]
+end
+\f[R]
+.fi
+.PP
+Notice the \f[C]CGI.escape\f[R] call in the second source.
+This is important, as it properly URL escapes the source URL so Gemstash
+knows what gem source you want.
+The \f[C]/upstream\f[R] prefix tells Gemstash to use a gem source other
+than the default source.
+You can now bundle with the additional source.
+.SS REDIRECTING
+.PP
+Gemstash supports an alternate mode of specifying your gem sources.
+If you want Gemstash to redirect Bundler to your given gem sources, then
+you can specify your \f[C]Gemfile\f[R] like so:
+.IP
+.nf
+\f[C]
+# ./Gemfile
+require \[dq]cgi\[dq]
+source \[dq]http://localhost:9292/redirect/#{CGI.escape(\[dq]https://rubygems.org\[dq])}\[dq]
+gem \[dq]rubywarrior\[dq]
+\f[R]
+.fi
+.PP
+Notice the \f[C]/redirect\f[R] prefix.
+This prefix tells Gemstash to redirect API calls to the provided URL.
+Redirected calls like this will not be cached by Gemstash, and gem files
+will not be stashed, even if they were previously cached or stashed from
+the same gem source.

data/lib/gemstash/man/gemstash-multiple-sources.7.txt

@@ -1,66 +1,71 @@
+gemstash-multiple-sources(7)			  gemstash-multiple-sources(7)
 
 
 
+1mMULTIPLE GEM SOURCES0m
+       Gemstash will stash from any amount of gem sources.  By the end of this
+       guide, you will be able to  bundle  using  multiple  gem	 sources,  all
+       stashed within your Gemstash server.
 
+   1mDEFAULT SOURCE0m
+       When you don't provide an explicit source (as with the Quickstart Guide
+       (../readme.md#quickstart-guide)),  your	gems  will  be	fetched	  from
+       https://rubygems.org.   This  default  source  is not set in stone.  To
+       change it, you need only	 edit  the  Gemstash  configuration  found  at
+       ~/.gemstash/config.yml:
 
+	      # ~/.gemstash/config.yml
+	      ---
+	      :rubygems_url: https://my.gem-source.local
 
+       Make sure to restart your Gemstash server after changing the config:
 
+	      $ gemstash stop
+	      $ gemstash start
 
+       Once  restarted, bundling against http://localhost:9292 will fetch gems
+       from https://my.gem-source.local.  If you  had  bundled	before	making
+       these  changes,	fear not; bundling with a different default gem source
+       will store gems in a  separate  location,  ensuring  different  sources
+       won't leak between each other.
 
+   1mBUNDLING WITH MULTIPLE SOURCES0m
+       Changing	 the  default  source  won't  help  you	 if you need to bundle
+       against https://rubygems.org along with	additional  sources.   If  you
+       need  to	 bundle with multiple gem sources, Gemstash doesn't need to be
+       specially configured.  Your Gemstash server will honor any  gem	source
+       specified via a specialized URL.	 Consider the following Gemfile:
 
+	      # ./Gemfile
+	      require "cgi"
+	      source "http://localhost:9292"
+	      gem "rubywarrior"
 
+	      source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
+		gem "my-gem"
+	      end
 
+       Notice the CGI.escape call in the second source.	 This is important, as
+       it properly URL escapes the source  URL	so  Gemstash  knows  what  gem
+       source  you  want.   The	 /upstream  prefix tells Gemstash to use a gem
+       source other than the default source.  You can now bundle with the  ad-
+       ditional source.
 
+   1mREDIRECTING0m
+       Gemstash supports an alternate mode of specifying your gem sources.  If
+       you want Gemstash to redirect Bundler to your given gem	sources,  then
+       you can specify your Gemfile like so:
 
+	      # ./Gemfile
+	      require "cgi"
+	      source "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
+	      gem "rubywarrior"
 
+       Notice  the  /redirect  prefix.	This prefix tells Gemstash to redirect
+       API calls to the provided URL.  Redirected calls like this will not  be
+       cached  by  Gemstash,  and  gem files will not be stashed, even if they
+       were previously cached or stashed from the same gem source.
 
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+				October 8, 2015	  gemstash-multiple-sources(7)

data/lib/gemstash/man/gemstash-private-gems.7

@@ -0,0 +1,227 @@
+.\" Automatically generated by Pandoc 2.5
+.\"
+.TH "gemstash\-private\-gems" "7" "October 8, 2015" "" ""
+.hy
+.SH PRIVATE GEMS
+.PP
+Stashing private gems in your Gemstash server requires a bit of
+additional setup.
+If you haven\[cq]t read through the Quickstart
+Guide (../readme.md#quickstart-guide), you should do that first.
+By the end of this guide, you will be able to interact with your
+Gemstash server to store and retrieve your private gems.
+.SS AUTHORIZING
+.PP
+\f[B]IMPORTANT NOTE:\f[R] Do not use the actual key value in this
+document, otherwise your Gemstash server will be vulnerable to anyone
+who wants to try to use the key against your server.
+Instead of the key value here, use whatever key is generated from
+running the commands.
+.PP
+In order to push a gem to your Gemstash server, you need to first create
+an API key.
+Utilize the \f[C]gemstash authorize\f[R] command to create the API key:
+.IP
+.nf
+\f[C]
+$ gemstash authorize
+Your new key is: e374e237fdf5fa5718d2a21bd63dc911
+\f[R]
+.fi
+.PP
+This new key can \f[C]push\f[R], \f[C]yank\f[R], and \f[C]fetch\f[R]
+gems from your Gemstash server.
+Run \f[C]gemstash authorize\f[R] with just the permissions you want to
+limit what the key will be allowed to do.
+You can similarly update a specific key by providing it via the
+\f[C]\-\-key\f[R] option:
+.IP
+.nf
+\f[C]
+$ gemstash authorize push yank \-\-key e374e237fdf5fa5718d2a21bd63dc911
+\f[R]
+.fi
+.PP
+When no permissions are provided (like the first example), the key will
+be authorized for all permissions.
+Leave the key authorized with everything if you want to use it to try
+all private gem interactions:
+.IP
+.nf
+\f[C]
+$ gemstash authorize \-\-key e374e237fdf5fa5718d2a21bd63dc911
+\f[R]
+.fi
+.PP
+With the key generated, you\[cq]ll need to tell Rubygems about your new
+key.
+If you\[cq]ve pushed a gem to https://rubygems.org, then you will
+already have a credentials file to add the key to.
+If not, run the following commands before modifying the credentials
+file:
+.IP
+.nf
+\f[C]
+$ mkdir \-p \[ti]/.gem
+$ touch \[ti]/.gem/credentials
+$ chmod 0600 \[ti]/.gem/credentials
+\f[R]
+.fi
+.PP
+Add your new key to credentials such that it looks something like this
+(but make sure not to remove any existing keys):
+.IP
+.nf
+\f[C]
+# \[ti]/.gem/credentials
+\-\-\-
+:test_key: e374e237fdf5fa5718d2a21bd63dc911
+\f[R]
+.fi
+.PP
+The name \f[C]test_key\f[R] can be anything you want, but you will need
+to remember it and use it again later in this guide for the
+\f[C]\-\-key\f[R] option.
+.SS CREATING A TEST GEM
+.PP
+You\[cq]ll need a test gem before you can play with private gems on your
+Gemstash server.
+If you have a gem you can use, move along to the next section.
+You can start by instantiating a test gem via Bundler:
+.IP
+.nf
+\f[C]
+$ bundle gem private\-example
+\f[R]
+.fi
+.PP
+You\[cq]ll need to add a summary and description to the new gem\[cq]s
+gemspec file in order to successfully build it.
+Once you\[cq]ve built the gem, you will be ready to push the new gem.
+.IP
+.nf
+\f[C]
+$ cd private\-example
+$ rake build
+\f[R]
+.fi
+.PP
+You will now have a gem at
+\f[C]private\-example/pkg/private\-example\-0.1.0.gem\f[R].
+.SS PUSHING
+.PP
+If your Gemstash server isn\[cq]t running, go ahead and start it:
+.IP
+.nf
+\f[C]
+$ gemstash start
+\f[R]
+.fi
+.PP
+Push your test gem using Rubygems:
+.IP
+.nf
+\f[C]
+$ gem push \-\-key test_key \-\-host http://localhost:9292/private pkg/private\-example\-0.1.0.gem
+\f[R]
+.fi
+.PP
+The \f[C]/private\f[R] portion of the \f[C]\-\-host\f[R] option tells
+Gemstash you are interacting with the private gems.
+Gemstash will not let you push, or yank from anything except
+\f[C]/private\f[R].
+.SS BUNDLING
+.PP
+Once your gem is pushed to your Gemstash server, you are ready to bundle
+it.
+Create a \f[C]Gemfile\f[R] and specify the gem.
+You will probably want to wrap the private gem in a source block, and
+let the rest of Gemstash handle all other gems:
+.IP
+.nf
+\f[C]
+# ./Gemfile
+source \[dq]http://localhost:9292\[dq]
+gem \[dq]rubywarrior\[dq]
+
+source \[dq]http://localhost:9292/private\[dq] do
+  gem \[dq]private\-example\[dq]
+end
+\f[R]
+.fi
+.PP
+Notice that the Gemstash server points to \f[C]/private\f[R] again when
+installing your private gem.
+Go ahead and bundle to install your new private gem:
+.IP
+.nf
+\f[C]
+$ bundle
+\f[R]
+.fi
+.SS YANKING
+.PP
+If you push a private gem by accident, you can yank the gem with
+Rubygems:
+.IP
+.nf
+\f[C]
+$ RUBYGEMS_HOST=http://localhost:9292/private gem yank \-\-key test_key private\-example \-\-version 0.1.0
+\f[R]
+.fi
+.PP
+Like with pushing, the \f[C]/private\f[R] portion of the host option
+tells Gemstash you are interacting with private gems.
+Gemstash will only let you yank from \f[C]/private\f[R].
+Unlike pushing, Rubygems doesn\[cq]t support \f[C]\-\-host\f[R] for yank
+(yet), so you need to specify the host via the \f[C]RUBYGEMS_HOST\f[R]
+environment variable.
+.SS PROTECTED FETCHING
+.PP
+By default, private gems and specs can be accessed without
+authentication.
+.PP
+Private gems often require protected fetching.
+For backwards compatibility this is disabled by default, but can be
+enabled via \f[C]$ gemstash setup\f[R] command.
+.PP
+When protected fetching is enabled API keys with the permissions
+\f[C]all\f[R] or \f[C]fetch\f[R] can be used to download gems and specs.
+.PP
+On the Bundler side, there are a few ways to configure credentials for a
+given gem source:
+.PP
+Add credentials globally:
+.IP
+.nf
+\f[C]
+$ bundle config my\-gemstash.dev api_key
+\f[R]
+.fi
+.PP
+Add credentials in Gemfile:
+.IP
+.nf
+\f[C]
+source \[dq]https://api_key\[at]my\-gemstash.dev\[dq]
+\f[R]
+.fi
+.PP
+However, it\[cq]s not a good practice to commit credentials to source
+control.
+A recommended solution is to use Bundler\[cq]s configuration
+keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS),
+e.g.:
+.IP
+.nf
+\f[C]
+$ export BUNDLE_MYGEMSTASH__DEV=api_key
+\f[R]
+.fi
+.PP
+Behind the scene, Bundler will pick up the ENV var according to the host
+name (e.g.\ mygemstash.dev) and add to \f[C]URI.userinfo\f[R] for making
+requests.
+.PP
+The API key is treated as a HTTP Basic Auth username and any HTTP Basic
+password supplied will be ignored.