gemstash 2.2.0 → 2.2.1

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

@@ -1 +1,158 @@
+gemstash-private-gems(7)			      gemstash-private-gems(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+1mPrivate Gems0m
+       Stashing  private  gems in your Gemstash server requires a bit of addi-
+       tional setup.  If you haven'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.
+
+   1mAuthorizing0m
+       1mIMPORTANT  NOTE: 22mDo not use the actual key value in this document, oth-
+       erwise 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.
+
+       In order to push a gem to your Gemstash server, you need to first  cre-
+       ate  an	API key.  Utilize the 1mgemstash authorize 22mcommand to create the
+       API key:
+
+	      $ gemstash authorize
+	      Your new key is: e374e237fdf5fa5718d2a21bd63dc911
+
+       This new key can 1mpush22m, 1myank22m, and 1mfetch 22mgems from your Gemstash  server.
+       Run 1mgemstash authorize 22mwith 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 1m--key 22moption:
+
+	      $ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
+
+       When no permissions are provided (like the first example), the key will
+       be authorized for all permissions.  Leave the key authorized  with  ev-
+       erything if you want to use it to try all private gem interactions:
+
+	      $ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
+
+       With  the  key  generated,  you'll need to tell Rubygems about your new
+       key.  If you've pushed a gem to https://rubygems.org, then you will al-
+       ready  have a credentials file to add the key to.  If not, run the fol-
+       lowing commands before modifying the credentials file:
+
+	      $ mkdir -p ~/.gem
+	      $ touch ~/.gem/credentials
+	      $ chmod 0600 ~/.gem/credentials
+
+       Add your new key to credentials such that it looks something like  this
+       (but make sure not to remove any existing keys):
+
+	      # ~/.gem/credentials
+	      ---
+	      :test_key: e374e237fdf5fa5718d2a21bd63dc911
+
+       The name 1mtest_key 22mcan be anything you want, but you will need to remem-
+       ber it and use it again later in this guide for the 1m--key 22moption.
+
+   1mCreating a Test Gem0m
+       You'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:
+
+	      $ bundle gem private-example
+
+       You'll need to add a summary and description to the new	gem's  gemspec
+       file in order to successfully build it.	Once you've built the gem, you
+       will be ready to push the new gem.
+
+	      $ cd private-example
+	      $ rake build
+
+       You  will  now  have   a   gem	at   1mprivate-example/pkg/private-exam-0m
+       1mple-0.1.0.gem22m.
+
+   1mPushing0m
+       If your Gemstash server isn't running, go ahead and start it:
+
+	      $ gemstash start
+
+       Push your test gem using Rubygems:
+
+	      $ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
+
+       The 1m/private 22mportion of the 1m--host 22moption tells Gemstash you are inter-
+       acting with the private gems.  Gemstash will not let you push, or  yank
+       from anything except 1m/private22m.
+
+   1mBundling0m
+       Once  your gem is pushed to your Gemstash server, you are ready to bun-
+       dle it.	Create a 1mGemfile 22mand 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:
+
+	      # ./Gemfile
+	      source "http://localhost:9292"
+	      gem "rubywarrior"
+
+	      source "http://localhost:9292/private" do
+		gem "private-example"
+	      end
+
+       Notice that the Gemstash server	points	to  1m/private	22magain  when	in-
+       stalling  your  private	gem.   Go ahead and bundle to install your new
+       private gem:
+
+	      $ bundle
+
+   1mYanking0m
+       If you push a private gem by  accident,	you  can  yank	the  gem  with
+       Rubygems:
+
+	      $ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
+
+       Like  with  pushing, the 1m/private 22mportion of the host option tells Gem-
+       stash you are interacting with private gems.  Gemstash  will  only  let
+       you  yank  from	1m/private22m.	 Unlike  pushing,  Rubygems doesn't support
+       1m--host 22mfor yank (yet),  so	you  need  to  specify	the  host  via	the
+       1mRUBYGEMS_HOST 22menvironment variable.
+
+   1mProtected Fetching0m
+       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 1m$ gemstash0m
+       1msetup 22mcommand.
+
+       When protected fetching is enabled API keys with the permissions 1mall 22mor
+       1mfetch 22mcan 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 1mURI.userinfo 22mfor 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

@@ -0,0 +1,245 @@
+<!-- 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-readme" "7" "November 30, 2015" "" ""
+.hy
+.SH Gemstash
+.SS What is Gemstash?
+.PP
+Gemstash is both a cache for remote servers such as
+https://rubygems.org, and a private gem source.
+.PP
+If you are using bundler (http://bundler.io/) across many machines that
+have access to a server within your control, you might want to use
+Gemstash.
+.PP
+If you produce gems that you don\[cq]t want everyone in the world to
+have access to, you might want to use Gemstash.
+.PP
+If you frequently bundle the same set of gems across multiple projects,
+you might want to use Gemstash.
+.PP
+Are you only using gems from https://rubygems.org, and don\[cq]t bundle
+the same gems frequently?
+Well, maybe you don\[cq]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
+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.
+.PP
+Install Gemstash to get started:
+.IP
+.nf
+\f[C]
+$ gem install gemstash
+\f[R]
+.fi
+.PP
+After it is installed, starting Gemstash requires no additional steps.
+Simply start the Gemstash server with the \f[V]gemstash\f[R] command:
+.IP
+.nf
+\f[C]
+$ gemstash start
+\f[R]
+.fi
+.PP
+You may have noticed that the command finished quickly.
+This is because Gemstash will run the server in the background by
+default.
+The server runs on port 9292.
+.SS Bundling
+.PP
+With the server running, you can bundle against it.
+Tell Bundler that you want to use Gemstash to find gems from
+RubyGems.org:
+.IP
+.nf
+\f[C]
+$ bundle config mirror.https://rubygems.org http://localhost:9292
+\f[R]
+.fi
+.PP
+Now you can create a Gemfile and install gems through Gemstash:
+.IP
+.nf
+\f[C]
+# ./Gemfile
+source \[dq]https://rubygems.org\[dq]
+gem \[dq]rubywarrior\[dq]
+\f[R]
+.fi
+.PP
+The gems you include should be gems you don\[cq]t yet have installed,
+otherwise Gemstash will have nothing to stash.
+Now bundle:
+.IP
+.nf
+\f[C]
+$ bundle install --path .bundle
+\f[R]
+.fi
+.PP
+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.
+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]
+$ # Disable your Internet first!
+$ rm -rf Gemfile.lock .bundle
+$ bundle
+\f[R]
+.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[R]
+.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[R]
+.fi
+.SS Stopping the Server
+.PP
+Once you\[cq]ve finish using your Gemstash server, you can stop it just
+as easily as you started it:
+.IP
+.nf
+\f[C]
+$ gemstash stop
+\f[R]
+.fi
+.PP
+You\[cq]ll also want to tell Bundler that it can go back to getting gems
+from RubyGems.org directly, instead of going through Gemstash:
+.IP
+.nf
+\f[C]
+$ bundle config --delete mirror.https://rubygems.org
+\f[R]
+.fi
+.SS Under the Hood
+.PP
+You might wonder where the gems are stored.
+After running the commands above, you will find a new directory at
+\f[V]\[ti]/.gemstash\f[R].
+This directory holds all the cached and private gems.
+It also has a server log, the database, and configuration for Gemstash.
+If you prefer, you can point to a different directory.
+.PP
+Gemstash uses SQLite (https://www.sqlite.org/) to store details about
+private gems.
+The database will be located in \f[V]\[ti]/.gemstash\f[R], however you
+won\[cq]t see the database appear until you start using private gems.
+If you prefer, you can use a different database.
+.PP
+Gemstash temporarily caches things like gem dependencies in memory.
+Anything cached in memory will last for 30 minutes before being
+retrieved again.
+You can use memcached instead of caching in memory.
+Gem files are always cached permanently, so bundling with a
+\f[V]Gemfile.lock\f[R] with all gems cached will never call out to
+https://rubygems.org.
+.PP
+The server you ran is provided via Puma (http://puma.io/) and
+Rack (http://rack.github.io/), however they are not customizable at this
+point.
+.SS Deep Dive
+.PP
+Deep dive into more subjects:
+.IP \[bu] 2
+Private gems
+.IP \[bu] 2
+Multiple gem sources
+.IP \[bu] 2
+Using Gemstash as a mirror
+.IP \[bu] 2
+Customizing the server (database, storage, caching, and more)
+.IP \[bu] 2
+Deploying Gemstash
+.IP \[bu] 2
+Debugging Gemstash
+.SS Reference
+.PP
+An anatomy of various configuration and commands:
+.IP \[bu] 2
+Configuration
+.IP \[bu] 2
+Authorize
+.IP \[bu] 2
+Start
+.IP \[bu] 2
+Stop
+.IP \[bu] 2
+Status
+.IP \[bu] 2
+Setup
+.IP \[bu] 2
+Version
+.PP
+To see what has changed in recent versions of Gemstash, see the
+CHANGELOG (https://github.com/rubygems/gemstash/blob/master/CHANGELOG.md).
+.SS Development
+.PP
+After checking out the repo, run \f[V]bin/setup\f[R] to install
+dependencies.
+Then, run \f[V]rake\f[R] to run RuboCop and the tests.
+While developing, you can run \f[V]bin/gemstash\f[R] to run Gemstash.
+You can also run \f[V]bin/console\f[R] for an interactive prompt that
+will allow you to experiment.
+.SS Contributing
+.PP
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/rubygems/gemstash.
+This project is intended to be a safe, welcoming space for
+collaboration, and contributors are expected to adhere to the
+Contributor
+Covenant (https://github.com/rubygems/gemstash/blob/master/CODE_OF_CONDUCT.md)
+code of conduct.
+.SS License
+.PP
+The gem is available as open source under the terms of the MIT
+License (http://opensource.org/licenses/MIT).

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

@@ -1 +1,182 @@
+gemstash-readme(7)					    gemstash-readme(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+1mGemstash0m
+   1mWhat is Gemstash?0m
+       Gemstash    is	 both	a   cache   for   remote   servers   such   as
+       https://rubygems.org, and a private gem source.
+
+       If you are using bundler (http://bundler.io/) across many machines that
+       have access to a server within your control, you might want to use Gem-
+       stash.
+
+       If you produce gems that you don't want everyone in the world  to  have
+       access to, you might want to use Gemstash.
+
+       If you frequently bundle the same set of gems across multiple projects,
+       you might want to use 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.
+
+   1mQuickstart Guide0m
+   1mSetup0m
+       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.
+
+       Install Gemstash to get started:
+
+	      $ gem install gemstash
+
+       After  it is installed, starting Gemstash requires no additional steps.
+       Simply start the Gemstash server with the 1mgemstash 22mcommand:
+
+	      $ 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
+       server runs on port 9292.
+
+   1mBundling0m
+       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
+
+       Now you can create a Gemfile and install gems through Gemstash:
+
+	      # ./Gemfile
+	      source "https://rubygems.org"
+	      gem "rubywarrior"
+
+       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.  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
+
+   1mFalling back to rubygems.org0m
+       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
+
+   1mStopping the Server0m
+       Once  you've finish using your Gemstash server, you can stop it just as
+       easily as you started it:
+
+	      $ gemstash stop
+
+       You'll also want to tell Bundler that it can go back  to  getting  gems
+       from RubyGems.org directly, instead of going through Gemstash:
+
+	      $ bundle config --delete mirror.https://rubygems.org
+
+   1mUnder the Hood0m
+       You might wonder where the gems are stored.  After running the commands
+       above, you will find a new directory at	1m~/.gemstash22m.   This  directory
+       holds  all  the cached and private gems.  It also has a server log, the
+       database, and configuration for Gemstash.  If you prefer, you can point
+       to a different directory.
+
+       Gemstash  uses  SQLite (https://www.sqlite.org/) to store details about
+       private gems.  The database will be located in 1m~/.gemstash22m, however you
+       won't  see  the database appear until you start using private gems.  If
+       you prefer, you can use a different database.
+
+       Gemstash temporarily caches things like	gem  dependencies  in  memory.
+       Anything  cached  in  memory  will last for 30 minutes before being re-
+       trieved again.  You can use memcached instead  of  caching  in  memory.
+       Gem  files  are	always	cached	permanently,  so  bundling with a 1mGem-0m
+       1mfile.lock   22mwith   all   gems   cached   will   never   call   out	 to
+       https://rubygems.org.
+
+       The  server  you  ran  is  provided via Puma (http://puma.io/) and Rack
+       (http://rack.github.io/), however they are  not	customizable  at  this
+       point.
+
+   1mDeep Dive0m
+       Deep dive into more subjects:
+
+       o Private gems
+
+       o Multiple gem sources
+
+       o Using Gemstash as a mirror
+
+       o Customizing the server (database, storage, caching, and more)
+
+       o Deploying Gemstash
+
+       o Debugging Gemstash
+
+   1mReference0m
+       An anatomy of various configuration and commands:
+
+       o Configuration
+
+       o Authorize
+
+       o Start
+
+       o Stop
+
+       o Status
+
+       o Setup
+
+       o Version
+
+       To  see	what  has  changed  in	recent	versions  of Gemstash, see the
+       CHANGELOG    (https://github.com/rubygems/gemstash/blob/master/CHANGEL-
+       OG.md).
+
+   1mDevelopment0m
+       After  checking	out  the  repo, run 1mbin/setup 22mto install dependencies.
+       Then, run 1mrake 22mto run RuboCop and the tests.  While developing, you can
+       run  1mbin/gemstash 22mto run Gemstash.	You can also run 1mbin/console 22mfor an
+       interactive prompt that will allow you to experiment.
+
+   1mContributing0m
+       Bug  reports   and   pull   requests   are   welcome   on   GitHub   at
+       https://github.com/rubygems/gemstash.  This project is intended to be a
+       safe, welcoming space for collaboration, and contributors are  expected
+       to adhere to the Contributor Covenant (https://github.com/rubygems/gem-
+       stash/blob/master/CODE_OF_CONDUCT.md) code of conduct.
+
+   1mLicense0m
+       The gem is available as open source under the terms of the MIT  License
+       (http://opensource.org/licenses/MIT).
+
+
+
+			       November 30, 2015	    gemstash-readme(7)

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

@@ -0,0 +1,58 @@
+<!-- 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-setup" "1" "October 9, 2015" "" ""
+.hy
+.SH Name
+.PP
+gemstash-setup - Customize your Gemstash configuration interactively
+.SH Synopsis
+.PP
+\f[V]gemstash setup [--redo] [--debug] [--config-file FILE]\f[R]
+.SH Description
+.PP
+Customize your Gemstash configuration interactively.
+This will save your config file, but only if a few checks pass after
+you\[cq]ve provided your answers.
+.SS Usage
+.IP
+.nf
+\f[C]
+gemstash setup
+gemstash setup --redo
+gemstash setup --config-file <file>
+\f[R]
+.fi
+.SH Options
+.IP \[bu] 2
+\f[V]--redo\f[R]: Redo the configuration.
+This does nothing the first time \f[V]gemstash setup\f[R] is run.
+If you want to change your configuration using \f[V]gemstash setup\f[R]
+after you\[cq]ve run it before, you must provide this option, otherwise
+Gemstash will simply indicate your setup is complete.
+.IP \[bu] 2
+\f[V]--debug\f[R]: Output additional information if one of the checks at
+the end of setup fails.
+This will do nothing if all checks pass.
+.IP \[bu] 2
+\f[V]--config-file FILE\f[R]: Specify the config file to write to.
+Without this option, your configuration will be written to
+\f[V]\[ti]/.gemstash/config.yml\f[R].
+If you write to a custom location, you will need to pass the
+\f[V]--config-file\f[R] option to all Gemstash commands.
+If you plan to use ERB in your config file, you might want to use
+\f[V]\[ti]/.gemstash/config.yml.erb\f[R].

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

@@ -1 +1,42 @@
+gemstash-setup(1)					     gemstash-setup(1)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+1mName0m
+       gemstash-setup - Customize your Gemstash configuration interactively
+
+1mSynopsis0m
+       1mgemstash setup [--redo] [--debug] [--config-file FILE]0m
+
+1mDescription0m
+       Customize  your	Gemstash  configuration interactively.	This will save
+       your config file, but only if a few checks pass after  you've  provided
+       your answers.
+
+   1mUsage0m
+	      gemstash setup
+	      gemstash setup --redo
+	      gemstash setup --config-file <file>
+
+1mOptions0m
+       o 1m--redo22m:  Redo  the  configuration.   This does nothing the first time
+	 1mgemstash setup 22mis run.  If you want to change your configuration	us-
+	 ing  1mgemstash setup 22mafter you've run it before, you must provide this
+	 option, otherwise Gemstash will simply indicate your  setup  is  com-
+	 plete.
+
+       o 1m--debug22m:	Output	additional  information if one of the checks at the
+	 end of setup fails.  This will do nothing if all checks pass.
+
+       o 1m--config-file FILE22m: Specify the config file  to  write  to.   Without
+	 this  option,	your configuration will be written to 1m~/.gemstash/con-0m
+	 1mfig.yml22m.	If you write to a custom location, you will  need  to  pass
+	 the  1m--config-file  22moption  to all Gemstash commands.  If you plan to
+	 use ERB in your config file, you might want to  use  1m~/.gemstash/con-0m
+	 1mfig.yml.erb22m.
+
+
+
+				October 9, 2015 	     gemstash-setup(1)