gemstash 1.0.2 → 1.0.3

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

@@ -0,0 +1,34 @@
+gemstash-deploy(7)					    gemstash-deploy(7)
+
+
+
+DEPLOYING GEMSTASH
+       Bundler	is  here  for the rescue to keep Gemstash up to date! Create a
+       Gemfile pointing to Gemstash:
+
+	      # ./Gemfile
+	      source "https://rubygems.org"
+	      gem "gemstash"
+
+       Then bundle to create your Gemfile.lock.  When you  are	ready  to  up-
+       grade,  simply  bundle update.	You  may need to run gemstash via bun-
+       dle exec.  Alternatively, you can  gem uninstall gemstash  and  gem in-
+       stall gemstash when you want to upgrade.
+
+       Gemstash  will  automatically run any necessary migrations, so updating
+       the gem is all that needs to be done.
+
+       It is probably wise to stop Gemstash before  upgrading,	then  starting
+       again once you are done:
+
+	      $ bundle exec gemstash stop
+	      $ bundle update
+	      $ bundle exec gemstash start
+
+   DOWNGRADING
+       It is not recommended to go backwards in Gemstash versions.  Migrations
+       may have run that could leave the database in a bad state.
+
+
+
+			       October 25, 2015 	    gemstash-deploy(7)

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

@@ -0,0 +1,40 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.TH "gemstash\-mirror" "7" "October 25, 2015" "" ""
+.hy
+.SH USING GEMSTASH AS A MIRROR
+.PP
+If you don\[aq]t have control over your \f[C]Gemfile\f[], or you
+don\[aq]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[C]Gemfile\f[], add a mirror pointing to your
+Gemstash server:
+.IP
+.nf
+\f[C]
+$\ 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("https://my.gem\-source.local")\[aq])
+\f[]
+.fi
+.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[C]1.11.0\f[].\f[]
+.PP
+If you are using Bundler version \f[C]1.11.0\f[] or greater, the
+mirroring becomes a bit easier:
+.IP
+.nf
+\f[C]
+$\ bundle\ config\ mirror.http://rubygems.org\ http://localhost:9292
+$\ bundle\ config\ mirror.https://my.gem\-source.local\ http://localhost:9292
+\f[]
+.fi
+.PP
+Bundler will then send headers to Gemstash to indicate the correct
+upstream.

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

@@ -0,0 +1,33 @@
+gemstash-mirror(7)					    gemstash-mirror(7)
+
+
+
+USING GEMSTASH AS A MIRROR
+       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 Gemfile, add a mirror pointing to your Gemstash
+       server:
+
+	      $ bundle config mirror.http://rubygems.org http://localhost:9292
+	      $ bundle config mirror.https://my.gem-source.local http://localhost:9292/upstream/$(ruby -rcgi -e 'puts CGI.escape("https://my.gem-source.local")')
+
+       From now on, bundler will fetch gems from those sources via  your  Gem-
+       stash server.
+
+SIMPLER GEMSTASH MIRRORS
+       This feature requires Bundler to be at least version 1.11.0.
+
+       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
+	      $ bundle config mirror.https://my.gem-source.local http://localhost:9292
+
+       Bundler will then send headers to Gemstash to indicate the correct  up-
+       stream.
+
+
+
+			       October 25, 2015 	    gemstash-mirror(7)

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

@@ -0,0 +1,89 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.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\[aq]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
+\f[C]~/.gemstash/config.yml\f[]:
+.IP
+.nf
+\f[C]
+#\ ~/.gemstash/config.yml
+\-\-\-
+:rubygems_url:\ https://my.gem\-source.local
+\f[]
+.fi
+.PP
+Make sure to restart your Gemstash server after changing the config:
+.IP
+.nf
+\f[C]
+$\ gemstash\ stop
+$\ gemstash\ start
+\f[]
+.fi
+.PP
+Once restarted, bundling against \f[C]http://localhost:9292\f[] will
+fetch gems from \f[C]https://my.gem\-source.local\f[].
+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\[aq]t leak between each other.
+.SS BUNDLING WITH MULTIPLE SOURCES
+.PP
+Changing the default source won\[aq]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\[aq]t
+need to be specially configured.
+Your Gemstash server will honor any gem source specified via a
+specialized URL.
+Consider the following \f[C]Gemfile\f[]:
+.IP
+.nf
+\f[C]
+#\ ./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
+\f[]
+.fi
+.PP
+Notice the \f[C]CGI.escape\f[] 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[C]/upstream\f[] prefix tells Gemstash to use a gem source other
+than the default source.
+You can now bundle with the additional source.
+.SS REDIRECTING
+.PP
+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[C]Gemfile\f[] like so:
+.IP
+.nf
+\f[C]
+#\ ./Gemfile
+require\ "cgi"
+source\ "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
+gem\ "rubywarrior"
+\f[]
+.fi
+.PP
+Notice the \f[C]/redirect\f[] 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.

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

@@ -0,0 +1,71 @@
+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

@@ -0,0 +1,195 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.TH "gemstash\-private\-gems" "7" "October 8, 2015" "" ""
+.hy
+.SH PRIVATE GEMS
+.PP
+Stashing private gems in your Gemstash server requires a bit of
+additional setup.
+If you haven\[aq]t read through the Quickstart
+Guide (gemstash 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.
+.SS AUTHORIZING
+.PP
+\f[B]IMPORTANT NOTE:\f[] Do not use the actual key value in this
+document, otherwise 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.
+.PP
+In order to push a gem to your Gemstash server, you need to first create
+an API key.
+Utilize the \f[C]gemstash\ authorize\f[] command to create the API key:
+.IP
+.nf
+\f[C]
+$\ gemstash\ authorize
+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.
+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
+\f[C]\-\-key\f[] option:
+.IP
+.nf
+\f[C]
+$\ gemstash\ authorize\ push\ yank\ \-\-key\ e374e237fdf5fa5718d2a21bd63dc911
+\f[]
+.fi
+.PP
+When no permissions are provided (like the first example), the key will
+be authorized for all permissions.
+Leave the key authorized with everything if you want to use it to try
+all private gem interactions:
+.IP
+.nf
+\f[C]
+$\ gemstash\ authorize\ \-\-key\ e374e237fdf5fa5718d2a21bd63dc911
+\f[]
+.fi
+.PP
+With the key generated, you\[aq]ll need to tell Rubygems about your new
+key.
+If you\[aq]ve pushed a gem to https://rubygems.org, then you will
+already have a credentials file to add the key to.
+If not, run the following commands before modifying the credentials
+file:
+.IP
+.nf
+\f[C]
+$\ mkdir\ \-p\ ~/.gem
+$\ touch\ ~/.gem/credentials
+$\ chmod\ 0600\ ~/.gem/credentials
+\f[]
+.fi
+.PP
+Add your new key to credentials such that it looks something like this
+(but make sure not to remove any existing keys):
+.IP
+.nf
+\f[C]
+#\ ~/.gem/credentials
+\-\-\-
+:test_key:\ e374e237fdf5fa5718d2a21bd63dc911
+\f[]
+.fi
+.PP
+The name \f[C]test_key\f[] can be anything you want, but you will need
+to remember it and use it again later in this guide for the
+\f[C]\-\-key\f[] option.
+.SS CREATING A TEST GEM
+.PP
+You\[aq]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:
+.IP
+.nf
+\f[C]
+$\ bundle\ gem\ private\-example
+\f[]
+.fi
+.PP
+You\[aq]ll need to add a summary and description to the new gem\[aq]s
+gemspec file in order to successfully build it.
+Once you\[aq]ve built the gem, you will be ready to push the new gem.
+.IP
+.nf
+\f[C]
+$\ cd\ private\-example
+$\ rake\ build
+\f[]
+.fi
+.PP
+You will now have a gem at
+\f[C]private\-example/pkg/private\-example\-0.1.0.gem\f[].
+.SS PUSHING
+.PP
+If your Gemstash server isn\[aq]t running, go ahead and start it:
+.IP
+.nf
+\f[C]
+$\ gemstash\ start
+\f[]
+.fi
+.PP
+Push your test gem using Rubygems:
+.IP
+.nf
+\f[C]
+$\ gem\ push\ \-\-key\ test_key\ \-\-host\ http://localhost:9292/private\ pkg/private\-example\-0.1.0.gem
+\f[]
+.fi
+.PP
+The \f[C]/private\f[] portion of the \f[C]\-\-host\f[] option tells
+Gemstash you are interacting with the private gems.
+Gemstash will not let you push, yank, or unyank from anything except
+\f[C]/private\f[].
+.SS BUNDLING
+.PP
+Once your gem is pushed to your Gemstash server, you are ready to bundle
+it.
+Create a \f[C]Gemfile\f[] 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:
+.IP
+.nf
+\f[C]
+#\ ./Gemfile
+source\ "http://localhost:9292"
+gem\ "rubywarrior"
+
+source\ "http://localhost:9292/private"\ do
+\ \ gem\ "private\-example"
+end
+\f[]
+.fi
+.PP
+Notice that the Gemstash server points to \f[C]/private\f[] again when
+installing your private gem.
+Go ahead and bundle to install your new private gem:
+.IP
+.nf
+\f[C]
+$\ bundle
+\f[]
+.fi
+.SS YANKING
+.PP
+If you push a private gem by accident, you can yank the gem with
+Rubygems:
+.IP
+.nf
+\f[C]
+$\ RUBYGEMS_HOST=http://localhost:9292/private\ gem\ yank\ \-\-key\ test_key\ private\-example\ \-\-version\ 0.1.0
+\f[]
+.fi
+.PP
+Like with pushing, the \f[C]/private\f[] portion of the host option
+tells Gemstash you are interacting with private gems.
+Gemstash will only let you yank from \f[C]/private\f[].
+Unlike pushing, Rubygems doesn\[aq]t support \f[C]\-\-host\f[] for yank
+and unyank (yet), so you need to specify the host via the
+\f[C]RUBYGEMS_HOST\f[] environment variable.
+.SS UNYANKING
+.PP
+If you yank a private gem by accident, you can unyank the gem with
+Rubygems:
+.IP
+.nf
+\f[C]
+$\ RUBYGEMS_HOST=http://localhost:9292/private\ gem\ yank\ \-\-key\ test_key\ private\-example\ \-\-version\ 0.1.0\ \-\-undo
+\f[]
+.fi
+.PP
+Like with pushing and yanking, the \f[C]/private\f[] portion of the host
+option tells Gemstash you are interacting with private gems.
+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.