gemstash 1.0.4 → 1.1.0

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

@@ -25,6 +25,31 @@ DEPLOYING GEMSTASH
 	      $ bundle update
 	      $ bundle exec gemstash start
 
+   MONITORING
+       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 /health from 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
+       /health/heartbeat which will always respond with a success  while  your
+       Gemstash server is running.
+
    DOWNGRADING
        It is not recommended to go backwards in Gemstash versions.  Migrations
        may have run that could leave the database in a bad state.

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-mirror" "7" "October 25, 2015" "" ""
 .hy

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-multiple\-sources" "7" "October 8, 2015" "" ""
 .hy

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-private\-gems" "7" "October 8, 2015" "" ""
 .hy
@@ -29,8 +29,8 @@ Your\ new\ key\ is:\ e374e237fdf5fa5718d2a21bd63dc911
 \f[]
 .fi
 .PP
-This new key can \f[C]push\f[], \f[C]yank\f[], and \f[C]unyank\f[] gems
-from your Gemstash server.
+This new key can \f[C]push\f[], \f[C]yank\f[], \f[C]unyank\f[], and
+\f[C]fetch\f[] gems from your Gemstash server.
 Run \f[C]gemstash\ authorize\f[] 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
@@ -193,3 +193,52 @@ Gemstash will only let you unyank from \f[C]/private\f[].
 Unlike pushing, Rubygems doesn\[aq]t support \f[C]\-\-host\f[] for
 unyank and yank (yet), so you need to specify the host via the
 \f[C]RUBYGEMS_HOST\f[] 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[] command.
+.PP
+When protected fetching is enabled API keys with the permissions
+\f[C]all\f[] or \f[C]fetch\f[] 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[]
+.fi
+.PP
+Add credentials in Gemfile:
+.IP
+.nf
+\f[C]
+source\ "https://api_key\@my\-gemstash.dev"
+\f[]
+.fi
+.PP
+However, it\[aq]s not a good practice to commit credentials to source
+control.
+A recommended solution is to use Bundler\[aq]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[]
+.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[] for making requests.
+.PP
+The API key is treated as a HTTP Basic Auth username and any HTTP Basic
+password supplied will be ignored.

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

@@ -22,10 +22,10 @@ PRIVATE GEMS
 	      $ gemstash authorize
 	      Your new key is: e374e237fdf5fa5718d2a21bd63dc911
 
-       This new key can push, yank, and unyank gems from your Gemstash server.
-       Run gemstash authorize 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 --key option:
+       This new key can push, yank, unyank, and fetch gems from your  Gemstash
+       server.	 Run  gemstash authorize 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 --key option:
 
 	      $ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
 
@@ -128,6 +128,41 @@ PRIVATE GEMS
        support	--host	for  unyank and yank (yet), so you need to specify the
        host via the RUBYGEMS_HOST environment variable.
 
+   PROTECTED FETCHING
+       By default, private gems and specs can be accessed without  authentica-
+       tion.
+
+       Private	gems often require protected fetching.	For backwards compati-
+       bility this is disabled by default,  but  can  be  enabled  via	$ gem-
+       stash setup command.
+
+       When protected fetching is enabled API keys with the permissions all or
+       fetch can be used to download gems and specs.
+
+       On the Bundler side, there are a few ways to configure credentials  for
+       a given gem source:
+
+       Add credentials globally:
+
+	      $ bundle config my-gemstash.dev api_key
+
+       Add credentials in Gemfile:
+
+	      source "https://api_key@my-gemstash.dev"
+
+       However,  it's not a good practice to commit credentials to source con-
+       trol.  A recommended solution is to use	Bundler's  configuration  keys
+       (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.:
+
+	      $ export BUNDLE_MYGEMSTASH__DEV=api_key
+
+       Behind  the  scene,  Bundler  will pick up the ENV var according to the
+       host name (e.g.	mygemstash.dev) and add to URI.userinfo for making re-
+       quests.
+
+       The API key is treated as a HTTP Basic Auth username and any HTTP Basic
+       password supplied will be ignored.
+
 
 
 				October 8, 2015       gemstash-private-gems(7)

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-readme" "7" "November 30, 2015" "" ""
 .hy
@@ -22,6 +22,14 @@ Are you only using gems from https://rubygems.org, and don\[aq]t bundle
 the same gems frequently?
 Well, maybe you don\[aq]t need Gemstash...
 yet.
+.PP
+Gemstash is maintained by Ruby Together (https://rubytogether.org/), a
+grassroots initiative committed to supporting the critical Ruby
+infrastructure you rely on.
+Contribute today as an individual (https://rubytogether.org/developers)
+or even better, as a company (https://rubytogether.org/companies), and
+ensure that Bundler, RubyGems, Gemstash, and other shared tooling is
+around for years to come.
 .SS QUICKSTART GUIDE
 .SS SETUP
 .PP
@@ -86,9 +94,10 @@ $\ bundle\ install\ \-\-path\ .bundle
 Your Gemstash server has fetched the gems from https://rubygems.org and
 cached them for you! To prove this, you can disable your Internet
 connection and try again.
-The gem dependencies from https://rubygems.org are cached for 30
-minutes, so if you bundle again before that, you can successfully bundle
-without an Internet connection:
+Gem files (*.gem) are cached indefinitely.
+Gem dependencies metadata are cached for 30 minutes, so if you bundle
+again before that, you can successfully bundle without an Internet
+connection:
 .IP
 .nf
 \f[C]
@@ -97,6 +106,27 @@ $\ rm\ \-rf\ Gemfile.lock\ .bundle
 $\ bundle
 \f[]
 .fi
+.SS FALLING BACK TO RUBYGEMS.ORG
+.PP
+If you want to make sure that your bundling from https://rubygems.org
+still works as expected when the Gemstash server is not running, you can
+easily configure Bundler to fallback to https://rubygems.org.
+.IP
+.nf
+\f[C]
+$\ bundle\ config\ mirror.https://rubygems.org.fallback_timeout\ true
+\f[]
+.fi
+.PP
+You can also configure this fallback as a number of seconds in case the
+Gemstash server is simply unresponsive.
+This example uses a 3 second timeout:
+.IP
+.nf
+\f[C]
+$\ bundle\ config\ mirror.https://rubygems.org.fallback_timeout\ 3
+\f[]
+.fi
 .SS STOPPING THE SERVER
 .PP
 Once you\[aq]ve finish using your Gemstash server, you can stop it just

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

@@ -20,27 +20,35 @@ GEMSTASH
        Are you only using gems from https://rubygems.org, and don't bundle the
        same gems frequently?  Well, maybe you don't need Gemstash...  yet.
 
+       Gemstash  is maintained by Ruby Together (https://rubytogether.org/), a
+       grassroots initiative committed to supporting the critical Ruby	infra-
+       structure   you	 rely	on.    Contribute   today   as	an  individual
+       (https://rubytogether.org/developers) or  even  better,	as  a  company
+       (https://rubytogether.org/companies),	and   ensure   that   Bundler,
+       RubyGems, Gemstash, and other shared tooling is	around	for  years  to
+       come.
+
    QUICKSTART GUIDE
    SETUP
        Gemstash  is  designed  to be quick and painless to get set up.	By the
        end of this Quickstart Guide, you will be able to bundle  stashed  gems
-       from public sources against a Gemstash server running on your machine.
+       from  public sources against a Gemstash server running on your machine.
 
        Install Gemstash to get started:
 
 	      $ gem install gemstash
 
-       After  it is installed, starting Gemstash requires no additional steps.
+       After it is installed, starting Gemstash requires no additional	steps.
        Simply start the Gemstash server with the gemstash command:
 
 	      $ gemstash start
 
-       You may have noticed that the command finished quickly.	 This  is  be-
-       cause  Gemstash	will run the server in the background by default.  The
+       You  may  have  noticed that the command finished quickly.  This is be-
+       cause Gemstash will run the server in the background by	default.   The
        server runs on port 9292.
 
    BUNDLING
-       With the server running, you can bundle against it.  Tell Bundler  that
+       With  the server running, you can bundle against it.  Tell Bundler that
        you want to use Gemstash to find gems from RubyGems.org:
 
 	      $ bundle config mirror.https://rubygems.org http://localhost:9292
@@ -51,21 +59,35 @@ GEMSTASH
 	      source "https://rubygems.org"
 	      gem "rubywarrior"
 
-       The  gems you include should be gems you don't yet have installed, oth-
+       The gems you include should be gems you don't yet have installed,  oth-
        erwise Gemstash will have nothing to stash.  Now bundle:
 
 	      $ bundle install --path .bundle
 
        Your Gemstash server has fetched the gems from https://rubygems.org and
-       cached  them for you! To prove this, you can disable your Internet con-
-       nection and try again.  The gem dependencies from  https://rubygems.org
-       are  cached for 30 minutes, so if you bundle again before that, you can
-       successfully bundle without an Internet connection:
+       cached them for you! To prove this, you can disable your Internet  con-
+       nection and try again.  Gem files (*.gem) are cached indefinitely.  Gem
+       dependencies metadata are cached for 30 minutes, so if you bundle again
+       before  that,  you  can successfully bundle without an Internet connec-
+       tion:
 
 	      $ # Disable your Internet first!
 	      $ rm -rf Gemfile.lock .bundle
 	      $ bundle
 
+   FALLING BACK TO RUBYGEMS.ORG
+       If you want to make sure that your bundling  from  https://rubygems.org
+       still  works  as  expected when the Gemstash server is not running, you
+       can easily configure Bundler to fallback to https://rubygems.org.
+
+	      $ bundle config mirror.https://rubygems.org.fallback_timeout true
+
+       You can also configure this fallback as a number of seconds in case the
+       Gemstash  server  is simply unresponsive.  This example uses a 3 second
+       timeout:
+
+	      $ bundle config mirror.https://rubygems.org.fallback_timeout 3
+
    STOPPING THE SERVER
        Once you've finish using your Gemstash server, you can stop it just  as
        easily as you started it:
@@ -87,8 +109,8 @@ GEMSTASH
        Gemstash uses SQLite (https://www.sqlite.org/) to store	details  about
        private gems.  The database will be located in ~/.gemstash, however you
        won't see the database appear until you start using private  gems.   If
-       you  prefer,  you  can  use a different database (gemstash help custom-
-       ize.7).
+       you  prefer,  you  can  use  a  different  database (gemstash help cus-
+       tomize.7).
 
        Gemstash temporarily caches things like	gem  dependencies  in  memory.
        Anything  cached  in  memory  will last for 30 minutes before being re-

data/lib/gemstash/man/gemstash-setup.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-setup" "1" "October 9, 2015" "" ""
 .hy
@@ -39,3 +39,5 @@ Without this option, your configuration will be written to
 \f[C]~/.gemstash/config.yml\f[].
 If you write to a custom location, you will need to pass the
 \f[C]\-\-config\-file\f[] option to all Gemstash commands.
+If you plan to use ERB in your config file (gemstash help customize.7),
+you might want to use \f[C]~/.gemstash/config.yml.erb\f[].

data/lib/gemstash/man/gemstash-setup.1.txt

@@ -31,7 +31,9 @@ OPTIONS
        o --config-file FILE: Specify the config file  to  write  to.   Without
 	 this  option,	your configuration will be written to ~/.gemstash/con-
 	 fig.yml.  If you write to a custom location, you will	need  to  pass
-	 the --config-file option to all Gemstash commands.
+	 the  --config-file  option  to all Gemstash commands.	If you plan to
+	 use ERB in your config file (gemstash help  customize.7),  you  might
+	 want to use ~/.gemstash/config.yml.erb.
 
 
 

data/lib/gemstash/man/gemstash-start.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-start" "1" "October 9, 2015" "" ""
 .hy
@@ -15,8 +15,9 @@ Starts the Gemstash server.
 .IP \[bu] 2
 \f[C]\-\-config\-file\ FILE\f[]: Specify the config file to use.
 If you aren\[aq]t using the default config file at
-\f[C]~/.gemstash/config.yml\f[], then you must specify the config file
-via this option.
+\f[C]~/.gemstash/config.yml\f[] or
+\f[C]~/.gemstash/config.yml.erb\f[] (gemstash help customize.7), then
+you must specify the config file via this option.
 .IP \[bu] 2
 \f[C]\-\-no\-daemonize\f[]: The Gemstash server daemonizes itself by
 default.

data/lib/gemstash/man/gemstash-start.1.txt

@@ -13,11 +13,12 @@ DESCRIPTION
 
 OPTIONS
        o --config-file FILE:  Specify  the  config file to use.  If you aren't
-	 using the default config file	at  ~/.gemstash/config.yml,  then  you
-	 must specify the config file via this option.
+	 using the default config file at  ~/.gemstash/config.yml  or  ~/.gem-
+	 stash/config.yml.erb (gemstash help customize.7), then you must spec-
+	 ify the config file via this option.
 
-       o --no-daemonize:  The  Gemstash  server  daemonizes itself by default.
-	 Provide this option to instead run the server until Ctrl-C is	typed.
+       o --no-daemonize: The Gemstash server  daemonizes  itself  by  default.
+	 Provide  this option to instead run the server until Ctrl-C is typed.
 	 When not daemonized, the log will be output to standard out.
 
 

data/lib/gemstash/man/gemstash-status.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-status" "1" "October 28, 2015" "" ""
 .hy
@@ -15,5 +15,6 @@ Checks status of the Gemstash server.
 .IP \[bu] 2
 \f[C]\-\-config\-file\ FILE\f[]: Specify the config file to use.
 If you aren\[aq]t using the default config file at
-\f[C]~/.gemstash/config.yml\f[], then you must specify the config file
-via this option.
+\f[C]~/.gemstash/config.yml\f[] or
+\f[C]~/.gemstash/config.yml.erb\f[] (gemstash help customize.7), then
+you must specify the config file via this option.

data/lib/gemstash/man/gemstash-status.1.txt

@@ -13,8 +13,9 @@ DESCRIPTION
 
 OPTIONS
        o --config-file FILE:  Specify  the  config file to use.  If you aren't
-	 using the default config file	at  ~/.gemstash/config.yml,  then  you
-	 must specify the config file via this option.
+	 using the default config file at  ~/.gemstash/config.yml  or  ~/.gem-
+	 stash/config.yml.erb (gemstash help customize.7), then you must spec-
+	 ify the config file via this option.
 
 
 

data/lib/gemstash/man/gemstash-stop.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-stop" "1" "October 9, 2015" "" ""
 .hy
@@ -15,5 +15,6 @@ Stops the Gemstash server.
 .IP \[bu] 2
 \f[C]\-\-config\-file\ FILE\f[]: Specify the config file to use.
 If you aren\[aq]t using the default config file at
-\f[C]~/.gemstash/config.yml\f[], then you must specify the config file
-via this option.
+\f[C]~/.gemstash/config.yml\f[] or
+\f[C]~/.gemstash/config.yml.erb\f[] (gemstash help customize.7), then
+you must specify the config file via this option.

data/lib/gemstash/man/gemstash-stop.1.txt

@@ -13,8 +13,9 @@ DESCRIPTION
 
 OPTIONS
        o --config-file FILE:  Specify  the  config file to use.  If you aren't
-	 using the default config file	at  ~/.gemstash/config.yml,  then  you
-	 must specify the config file via this option.
+	 using the default config file at  ~/.gemstash/config.yml  or  ~/.gem-
+	 stash/config.yml.erb (gemstash help customize.7), then you must spec-
+	 ify the config file via this option.
 
 
 

data/lib/gemstash/man/gemstash-version.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-version" "1" "December 14, 2015" "" ""
 .hy