gemstash 1.1.0 → 2.0.0

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

@@ -1,71 +1,66 @@
-gemstash-multiple-sources(7)			  gemstash-multiple-sources(7)
 
 
 
-MULTIPLE GEM SOURCES
-       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.
 
-   DEFAULT SOURCE
-       When you don't provide an explicit source (as with the Quickstart Guide
-       (gemstash  help	readme.7)),   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
-       ~/.gemstash/config.yml:
 
-	      # ~/.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 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.
 
-   BUNDLING WITH MULTIPLE SOURCES
-       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 Gemfile:
 
-	      # ./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 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  /upstream  prefix tells Gemstash to use a gem
-       source other than the default source.  You can now bundle with the  ad-
-       ditional source.
 
-   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 Gemfile like so:
 
-	      # ./Gemfile
-	      require "cgi"
-	      source "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
-	      gem "rubywarrior"
 
-       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   gemstash-multiple-sources(7)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

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

@@ -1,168 +1,66 @@
-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, 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
 
-       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.
 
-   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.txt

@@ -1,182 +1,66 @@
-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.
 
-       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.
 
-       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.  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:
 
-	      $ 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 cus-
-       tomize.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)
+
+
+
+
+
+
+
+
+
+