gemstash 1.0.2 → 1.0.3

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

@@ -0,0 +1,133 @@
+gemstash-private-gems(7)			      gemstash-private-gems(7)
+
+
+
+PRIVATE GEMS
+       Stashing  private  gems in your Gemstash server requires a bit of addi-
+       tional setup.  If you haven't read through the Quickstart  Guide  (gem-
+       stash  help  readme.7),	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.
+
+   AUTHORIZING
+       IMPORTANT  NOTE: Do 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 gemstash authorize command to create the
+       API key:
+
+	      $ 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:
+
+	      $ 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 test_key can be anything you want, but you will need to remem-
+       ber it and use it again later in this guide for the --key option.
+
+   CREATING A TEST GEM
+       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   private-example/pkg/private-exam-
+       ple-0.1.0.gem.
+
+   PUSHING
+       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 /private portion of the --host option tells Gemstash you are inter-
+       acting with the private gems.  Gemstash will not let you push, yank, or
+       unyank from anything except /private.
+
+   BUNDLING
+       Once  your gem is pushed to your Gemstash server, you are ready to bun-
+       dle it.	Create a Gemfile 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:
+
+	      # ./Gemfile
+	      source "http://localhost:9292"
+	      gem "rubywarrior"
+
+	      source "http://localhost:9292/private" do
+		gem "private-example"
+	      end
+
+       Notice that the Gemstash server	points	to  /private  again  when  in-
+       stalling  your  private	gem.   Go ahead and bundle to install your new
+       private gem:
+
+	      $ bundle
+
+   YANKING
+       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 /private portion of the host option tells Gem-
+       stash you are interacting with private gems.  Gemstash  will  only  let
+       you  yank  from	/private.   Unlike  pushing,  Rubygems doesn't support
+       --host for yank and unyank (yet), so you need to specify the  host  via
+       the RUBYGEMS_HOST environment variable.
+
+   UNYANKING
+       If  you	yank  a  private  gem by accident, you can unyank the gem with
+       Rubygems:
+
+	      $ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0 --undo
+
+       Like with pushing and yanking, the /private portion of the host	option
+       tells  Gemstash	you  are interacting with private gems.  Gemstash will
+       only let you unyank from /private.  Unlike  pushing,  Rubygems  doesn't
+       support	--host	for  unyank and yank (yet), so you need to specify the
+       host via the RUBYGEMS_HOST environment variable.
+
+
+
+				October 8, 2015       gemstash-private-gems(7)

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

@@ -0,0 +1,204 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.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\[aq]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\[aq]t bundle
+the same gems frequently?
+Well, maybe you don\[aq]t need Gemstash...
+yet.
+.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[]
+.fi
+.PP
+After it is installed, starting Gemstash requires no additional steps.
+Simply start the Gemstash server with the \f[C]gemstash\f[] command:
+.IP
+.nf
+\f[C]
+$\ gemstash\ start
+\f[]
+.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[]
+.fi
+.PP
+Now you can create a Gemfile and install gems through Gemstash:
+.IP
+.nf
+\f[C]
+#\ ./Gemfile
+source\ "https://rubygems.org"
+gem\ "rubywarrior"
+\f[]
+.fi
+.PP
+The gems you include should be gems you don\[aq]t yet have installed,
+otherwise Gemstash will have nothing to stash.
+Now bundle:
+.IP
+.nf
+\f[C]
+$\ bundle\ install\ \-\-path\ .bundle
+\f[]
+.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.
+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:
+.IP
+.nf
+\f[C]
+$\ #\ Disable\ your\ Internet\ first!
+$\ rm\ \-rf\ Gemfile.lock\ .bundle
+$\ bundle
+\f[]
+.fi
+.SS STOPPING THE SERVER
+.PP
+Once you\[aq]ve finish using your Gemstash server, you can stop it just
+as easily as you started it:
+.IP
+.nf
+\f[C]
+$\ gemstash\ stop
+\f[]
+.fi
+.PP
+You\[aq]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[]
+.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[C]~/.gemstash\f[].
+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 help customize.7).
+.PP
+Gemstash uses SQLite (https://www.sqlite.org/) to store details about
+private gems.
+The database will be located in \f[C]~/.gemstash\f[], however you
+won\[aq]t see the database appear until you start using private gems.
+If you prefer, you can use a different
+database (gemstash help customize.7).
+.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 (gemstash help customize.7) instead of caching in
+memory.
+Gem files are always cached permanently, so bundling with a
+\f[C]Gemfile.lock\f[] 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 (gemstash help private-gems.7)
+.IP \[bu] 2
+Multiple gem sources (gemstash help multiple-sources.7)
+.IP \[bu] 2
+Using Gemstash as a mirror (gemstash help mirror.7)
+.IP \[bu] 2
+Customizing the server (database, storage, caching, and
+more) (gemstash help customize.7)
+.IP \[bu] 2
+Deploying Gemstash (gemstash help deploy.7)
+.IP \[bu] 2
+Debugging Gemstash (gemstash help debugging.7)
+.SS REFERENCE
+.PP
+An anatomy of various configuration and commands:
+.IP \[bu] 2
+Configuration (gemstash help configuration.5)
+.IP \[bu] 2
+Authorize (gemstash help authorize.1)
+.IP \[bu] 2
+Start (gemstash help start.1)
+.IP \[bu] 2
+Stop (gemstash help stop.1)
+.IP \[bu] 2
+Status (gemstash help status.1)
+.IP \[bu] 2
+Setup (gemstash help setup.1)
+.IP \[bu] 2
+Version (gemstash help version.1)
+.PP
+To see what has changed in recent versions of Gemstash, see the
+CHANGELOG (https://github.com/bundler/gemstash/blob/master/CHANGELOG.md).
+.SS DEVELOPMENT
+.PP
+After checking out the repo, run \f[C]bin/setup\f[] to install
+dependencies.
+Then, run \f[C]rake\f[] to run RuboCop and the tests.
+While developing, you can run \f[C]bin/gemstash\f[] to run Gemstash.
+You can also run \f[C]bin/console\f[] 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/bundler/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/bundler/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

@@ -0,0 +1,160 @@
+gemstash-readme(7)					    gemstash-readme(7)
+
+
+
+GEMSTASH
+   WHAT IS GEMSTASH?
+       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.
+
+   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.
+
+       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 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
+       server runs on port 9292.
+
+   BUNDLING
+       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.  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:
+
+	      $ # Disable your Internet first!
+	      $ rm -rf Gemfile.lock .bundle
+	      $ bundle
+
+   STOPPING THE SERVER
+       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
+
+   UNDER THE HOOD
+       You might wonder where the gems are stored.  After running the commands
+       above,  you  will  find a new directory at ~/.gemstash.	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 help customize.7).
+
+       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).
+
+       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 (gemstash help  customize.7)  in-
+       stead  of  caching in memory.  Gem files are always cached permanently,
+       so bundling with a Gemfile.lock with 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.
+
+   DEEP DIVE
+       Deep dive into more subjects:
+
+       o Private gems (gemstash help private-gems.7)
+
+       o Multiple gem sources (gemstash help multiple-sources.7)
+
+       o Using Gemstash as a mirror (gemstash help mirror.7)
+
+       o Customizing  the  server (database, storage, caching, and more) (gem-
+	 stash help customize.7)
+
+       o Deploying Gemstash (gemstash help deploy.7)
+
+       o Debugging Gemstash (gemstash help debugging.7)
+
+   REFERENCE
+       An anatomy of various configuration and commands:
+
+       o Configuration (gemstash help configuration.5)
+
+       o Authorize (gemstash help authorize.1)
+
+       o Start (gemstash help start.1)
+
+       o Stop (gemstash help stop.1)
+
+       o Status (gemstash help status.1)
+
+       o Setup (gemstash help setup.1)
+
+       o Version (gemstash help version.1)
+
+       To see what has	changed  in  recent  versions  of  Gemstash,  see  the
+       CHANGELOG     (https://github.com/bundler/gemstash/blob/master/CHANGEL-
+       OG.md).
+
+   DEVELOPMENT
+       After checking out the repo, run  bin/setup  to	install  dependencies.
+       Then, run rake to run RuboCop and the tests.  While developing, you can
+       run bin/gemstash to run Gemstash.  You can also run bin/console for  an
+       interactive prompt that will allow you to experiment.
+
+   CONTRIBUTING
+       Bug   reports   and   pull   requests   are   welcome   on   GitHub  at
+       https://github.com/bundler/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/bundler/gem-
+       stash/blob/master/CODE_OF_CONDUCT.md) code of conduct.
+
+   LICENSE
+       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)