gemstash 2.3.2 → 2.5.0

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

@@ -4,16 +4,16 @@
 
 1mDeploying Gemstash0m
        Bundler	is  here for the rescue to keep Gemstash up to date!  Create a
-       1mGemfile 22mpointing to Gemstash:
+       Gemfile pointing 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.
+       Then bundle to create your Gemfile.lock.  When you  are	ready  to  up-
+       grade,  simply  bundle update.  You may need to run gemstash via bundle
+       exec.  Alternatively, you can gem uninstall gemstash  and  gem  install
+       gemstash when you want to upgrade.
 
        Gemstash  will  automatically run any necessary migrations, so updating
        the gem is all that needs to be done.
@@ -26,12 +26,12 @@
 	      $ 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:
+       Health	 monitoring    is    built    in   to	Gemstash   using   the
+       server_health_check-rack 		       (https://github.com/on-
+       site/server_health_check-rack)  gem.   If you request /health from your
+       Gemstash instance, you will get a JSON response along with an HTTP sta-
+       tus code indicating success or failure.	The JSON  response  will  look
+       something like this for a success case:
 
 	      {
 		"status": {
@@ -43,11 +43,11 @@
 		}
 	      }
 
-       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
+       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
+       /health/heartbeat  which  will always respond with a success while your
        Gemstash server is running.
 
    1mDowngrading0m

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

@@ -1,55 +1,34 @@
 <!-- Automatically generated by Pandoc -->
-.\" Automatically generated by Pandoc 3.1.6.2
+.\" Automatically generated by Pandoc 3.1.8
 .\"
-.\" 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
+If you don\[cq]t have control over your \f[CR]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:
+For each source in your \f[CR]Gemfile\f[R], add a mirror pointing to
+your Gemstash server:
 .IP
-.nf
-\f[C]
+.EX
 $ 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
+.EE
 .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]
+\f[CB]1.11.0\f[B].\f[R]
 .PP
-If you are using Bundler version \f[V]1.11.0\f[R] or greater, the
+If you are using Bundler version \f[CR]1.11.0\f[R] or greater, the
 mirroring becomes a bit easier:
 .IP
-.nf
-\f[C]
+.EX
 $ bundle config mirror.http://rubygems.org http://localhost:9292
 $ bundle config mirror.https://my.gem-source.local http://localhost:9292
-\f[R]
-.fi
+.EE
 .PP
 Bundler will then send headers to Gemstash to indicate the correct
 upstream.

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

@@ -3,11 +3,11 @@
 <!-- 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
+       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 1mGemfile22m, add a mirror pointing to your Gemstash
+       For each source in your Gemfile, add a mirror pointing to your Gemstash
        server:
 
 	      $ bundle config mirror.http://rubygems.org http://localhost:9292
@@ -19,7 +19,7 @@
 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-
+       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

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

@@ -1,69 +1,46 @@
 <!-- Automatically generated by Pandoc -->
-.\" Automatically generated by Pandoc 3.1.6.2
+.\" Automatically generated by Pandoc 3.1.8
 .\"
-.\" 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]:
+\f[CR]\[ti]/.gemstash/config.yml\f[R]:
 .IP
-.nf
-\f[C]
+.EX
 # \[ti]/.gemstash/config.yml
 ---
 :rubygems_url: https://my.gem-source.local
-\f[R]
-.fi
+.EE
 .PP
 Make sure to restart your Gemstash server after changing the config:
 .IP
-.nf
-\f[C]
+.EX
 $ gemstash stop
 $ gemstash start
-\f[R]
-.fi
+.EE
 .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].
+Once restarted, bundling against \f[CR]http://localhost:9292\f[R] will
+fetch gems from \f[CR]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]:
+Consider the following \f[CR]Gemfile\f[R]:
 .IP
-.nf
-\f[C]
+.EX
 # ./Gemfile
 require \[dq]cgi\[dq]
 source \[dq]http://localhost:9292\[dq]
@@ -72,31 +49,82 @@ 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
+
+source \[dq]http://localhost:9292/upstream/my-other.gem-source.local\[dq] do
+  gem \[dq]my-other-gem\[dq]
+end
+.EE
 .PP
-Notice the \f[V]CGI.escape\f[R] call in the second source.
+Notice the \f[CR]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
+The \f[CR]/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
+Notice that the third source doesn\[cq]t need to be escaped.
+This is because the \f[CR]https://\f[R] is used by default when no
+scheme is set, and the source URL does not contain any characters that
+need to be escaped.
+.SS Authentication with Multiple Sources
+You can use basic authentication or API keys on sources directly in
+Gemfile or using ENV variables on the Gemstash instance.
+.PP
+Example \f[CR]Gemfile\f[R]:
+.IP
+.EX
+# ./Gemfile
+require \[dq]cgi\[dq]
+source \[dq]http://localhost:9292\[dq]
+
+source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]user:password\[at]my.gem-source.local\[dq])}\[dq] do
+  gem \[dq]my-gem\[dq]
+end
+
+source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]api_key\[at]my-other.gem-source.local\[dq])}\[dq] do
+  gem \[dq]my-other-gem\[dq]
+end
+.EE
+.PP
+If you set \f[CR]GEMSTASH_<HOST>\f[R] ENV variable with your
+authentication information, you can omit it from the \f[CR]Gemfile\f[R]:
+.IP
+.EX
+# ./Gemfile
+source \[dq]http://localhost:9292\[dq]
+
+source \[dq]http://localhost:9292/upstream/my.gem-source.local\[dq] do
+  gem \[dq]my-gem\[dq]
+end
+.EE
+.PP
+And run the Gemstash with the credentials set in an ENV variable:
+.IP
+.EX
+GEMSTASH_MY__GEM___SOURCE__LOCAL=user:password gemstash start --no-daemonize --config-file config.yml.erb
+.EE
+.PP
+The name of the ENV variable is the uppercase version of the host name,
+with all \f[CR].\f[R] characters replaced with \f[CR]__\f[R], all
+\f[CR]-\f[R] with \f[CR]___\f[R] and a \f[CR]GEMSTASH_\f[R] prefix (it
+uses the same syntax as
+Bundler (https://bundler.io/v2.4/man/bundle-config.1.html#CREDENTIALS-FOR-GEM-SOURCES)).
+.PP
+Example: \f[CR]my.gem-source.local\f[R] =>
+\f[CR]GEMSTASH_MY__GEM___SOURCE__LOCAL\f[R]
+.SS Redirecting
 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:
+you can specify your \f[CR]Gemfile\f[R] like so:
 .IP
-.nf
-\f[C]
+.EX
 # ./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
+.EE
 .PP
-Notice the \f[V]/redirect\f[R] prefix.
+Notice the \f[CR]/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

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

@@ -11,7 +11,7 @@
        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 configuration found at ~/.gemstash/config.yml:
 
 	      # ~/.gemstash/config.yml
 	      ---
@@ -22,8 +22,8 @@
 	      $ 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
+       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.
@@ -33,7 +33,7 @@
        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:
+       specified via a specialized URL.  Consider the following Gemfile:
 
 	      # ./Gemfile
 	      require "cgi"
@@ -44,25 +44,73 @@
 		gem "my-gem"
 	      end
 
-       Notice the 1mCGI.escape 22mcall in the second source.  This is important, as
+	      source "http://localhost:9292/upstream/my-other.gem-source.local" do
+		gem "my-other-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  1m/upstream  22mprefix tells Gemstash to use a 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.
 
+       Notice  that  the third source doesn't need to be escaped.  This is be-
+       cause the https:// is used by default when no scheme is	set,  and  the
+       source URL does not contain any characters that need to be escaped.
+
+   1mAuthentication with Multiple Sources0m
+       You  can  use  basic  authentication or API keys on sources directly in
+       Gemfile or using ENV variables on the Gemstash instance.
+
+       Example Gemfile:
+
+	      # ./Gemfile
+	      require "cgi"
+	      source "http://localhost:9292"
+
+	      source "http://localhost:9292/upstream/#{CGI.escape("user:password@my.gem-source.local")}" do
+		gem "my-gem"
+	      end
+
+	      source "http://localhost:9292/upstream/#{CGI.escape("api_key@my-other.gem-source.local")}" do
+		gem "my-other-gem"
+	      end
+
+       If you set GEMSTASH_<HOST> ENV variable with your authentication infor-
+       mation, you can omit it from the Gemfile:
+
+	      # ./Gemfile
+	      source "http://localhost:9292"
+
+	      source "http://localhost:9292/upstream/my.gem-source.local" do
+		gem "my-gem"
+	      end
+
+       And run the Gemstash with the credentials set in an ENV variable:
+
+	      GEMSTASH_MY__GEM___SOURCE__LOCAL=user:password gemstash start --no-daemonize --config-file config.yml.erb
+
+       The name of the ENV variable is the uppercase version of the host name,
+       with all . characters replaced with __, all - with ___ and a  GEMSTASH_
+       prefix	   (it	   uses     the     same     syntax	as     Bundler
+       (https://bundler.io/v2.4/man/bundle-config.1.html#CREDENTIALS-FOR-GEM-
+       SOURCES)).
+
+       Example: my.gem-source.local => GEMSTASH_MY__GEM___SOURCE__LOCAL
+
    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:
+       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 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
+       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   4mgemstash-multiple-sources24m(7)