gemstash 2.2.0 → 2.2.1

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

@@ -1 +1,61 @@
+gemstash-deploy(7)					    gemstash-deploy(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+1mDeploying Gemstash0m
+       Bundler	is  here for the rescue to keep Gemstash up to date!  Create a
+       1mGemfile 22mpointing to Gemstash:
+
+	      # ./Gemfile
+	      source "https://rubygems.org"
+	      gem "gemstash"
+
+       Then 1mbundle 22mto create your 1mGemfile.lock22m.  When you  are  ready  to  up-
+       grade,  simply  1mbundle update22m.  You may need to run 1mgemstash 22mvia 1mbundle0m
+       1mexec22m.  Alternatively, you can 1mgem uninstall gemstash  22mand  1mgem  install0m
+       1mgemstash 22mwhen you want to upgrade.
+
+       Gemstash  will  automatically run any necessary migrations, so updating
+       the gem is all that needs to be done.
+
+       It is probably wise to stop Gemstash before  upgrading,	then  starting
+       again once you are done:
+
+	      $ bundle exec gemstash stop
+	      $ bundle update
+	      $ bundle exec gemstash start
+
+   1mMonitoring0m
+       Health	monitoring   is   built   in   to  Gemstash  using  the  serv-
+       er_health_check-rack   (https://github.com/on-site/server_health_check-
+       rack)  gem.   If  you  request 1m/health 22mfrom your Gemstash instance, you
+       will get a JSON response along with an HTTP status code indicating suc-
+       cess or failure.  The JSON response will look something like this for a
+       success case:
+
+	      {
+		"status": {
+		  "heartbeat": "OK",
+		  "storage_read": "OK",
+		  "storage_write": "OK",
+		  "db_read": "OK",
+		  "db_write": "OK"
+		}
+	      }
+
+       This request will test storage and database access and  report  on  the
+       result.	 Each  key in the status can be requested alone to just report
+       on that status.	For example, if you would like	a  health  check  that
+       doesn't	 interact   with   storage   or  the  database,  you  can  use
+       1m/health/heartbeat 22mwhich will always respond with a success	while  your
+       Gemstash server is running.
+
+   1mDowngrading0m
+       It is not recommended to go backwards in Gemstash versions.  Migrations
+       may have run that could leave the database in a bad state.
+
+
+
+			       October 25, 2015 	    gemstash-deploy(7)

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

@@ -0,0 +1,55 @@
+<!-- Automatically generated by Pandoc -->
+.\" Automatically generated by Pandoc 3.0.1
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.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[V]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[V]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[VB]1.11.0\f[B].\f[R]
+.PP
+If you are using Bundler version \f[V]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 +1,35 @@
+gemstash-mirror(7)					    gemstash-mirror(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+1mUsing Gemstash as a Mirror0m
+       If you don't have control over your 1mGemfile22m, 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 1mGemfile22m, 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 1m1.11.0 22mor 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,103 @@
+<!-- Automatically generated by Pandoc -->
+.\" Automatically generated by Pandoc 3.0.1
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.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), 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[V]\[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[V]http://localhost:9292\f[R] will
+fetch gems from \f[V]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[V]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[V]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[V]/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[V]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[V]/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 +1,72 @@
+gemstash-multiple-sources(7)			  gemstash-multiple-sources(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+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), your gems will be fetched from https://rubygems.org.  This  de-
+       fault source is not set in stone.  To change it, you need only edit the
+       Gemstash configuration found at 1m~/.gemstash/config.yml22m:
+
+	      # ~/.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 1mhttp://localhost:9292 22mwill fetch  gems
+       from  1mhttps://my.gem-source.local22m.	 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 1mGemfile22m:
+
+	      # ./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 1mCGI.escape 22mcall in the second source.  This is important, as
+       it  properly  URL  escapes  the	source	URL so Gemstash knows what gem
+       source you want.  The 1m/upstream 22mprefix 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 1mGemfile 22mlike so:
+
+	      # ./Gemfile
+	      require "cgi"
+	      source "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
+	      gem "rubywarrior"
+
+       Notice the 1m/redirect 22mprefix.  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,242 @@
+<!-- Automatically generated by Pandoc -->
+.\" Automatically generated by Pandoc 3.0.1
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.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, 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[V]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[V]push\f[R], \f[V]yank\f[R], and \f[V]fetch\f[R]
+gems from your Gemstash server.
+Run \f[V]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[V]--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[V]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[V]--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[V]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[V]/private\f[R] portion of the \f[V]--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[V]/private\f[R].
+.SS Bundling
+.PP
+Once your gem is pushed to your Gemstash server, you are ready to bundle
+it.
+Create a \f[V]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[V]/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[V]/private\f[R] portion of the host option
+tells Gemstash you are interacting with private gems.
+Gemstash will only let you yank from \f[V]/private\f[R].
+Unlike pushing, Rubygems doesn\[cq]t support \f[V]--host\f[R] for yank
+(yet), so you need to specify the host via the \f[V]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[V]$ gemstash setup\f[R] command.
+.PP
+When protected fetching is enabled API keys with the permissions
+\f[V]all\f[R] or \f[V]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[V]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.