gemstash 2.1.0 → 2.2.0

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

@@ -1,187 +1 @@
-gemstash-customize(7)					 gemstash-customize(7)
 
-
-
-1mCUSTOMIZING THE SERVER0m
-       Although	 Gemstash  is designed for as minimal setup as possible, there
-       may be times you will want to change some of the default configuration.
-       By  the	end  of	 this guide, you will be able to customize some of the
-       Gemstash behavior, including where files are stored, what database Gem-
-       stash uses, and how Gemstash caches certain requests.
-
-   1mSETUP0m
-       Several	customizable options are available via an interactive Gemstash
-       command.	 Run gemstash setup and answer the questions  it  provides  (a
-       blank answer will use the default value):
-
-	      $ gemstash setup
-	      Where should files go?  [~/.gemstash]
-	      Cache with what?	[MEMORY, memcached] 1mmemcached0m
-	      What   is	  the  comma  separated	 Memcached  servers?   [local-
-	      host:11211]
-	      What database adapter?  [SQLITE3, postgres, mysql, mysql2] 1mpost-0m
-	      1mgres0m
-	      Where is the database?  [postgres:///gemstash]
-	      Checking that the cache is available
-	      Checking that the database is available
-	      The database is not available
-       Once  you've answered the questions, some checks will be made to ensure
-       the configuration will work.  For example, the database didn't exist in
-       the  previous  example,	so  the	 command  failed and the configuration
-       wasn't saved.  If the command passes, you may provide the --redo option
-       to force configuration to be redone:
-
-	      $ gemstash setup --redo
-	      Where should files go?  [~/.gemstash]
-	      Cache with what?	[MEMORY, memcached] 1mmemcached0m
-	      What   is	  the  comma  separated	 Memcached  servers?   [local-
-	      host:11211]
-	      What database adapter?  [SQLITE3, postgres, mysql, mysql2]
-	      Checking that the cache is available
-	      Checking that the database is available
-	      You are all setup!
-       Once all checks have passed, Gemstash will store your  answers  in  the
-       configuration file located at ~/.gemstash/config.yml.
-
-   1mFILES0m
-       Storage in Gemstash defaults to ~/.gemstash unless otherwise specified.
-       You can change this in your config file via the :base_path key:
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :base_path: "/var/gemstash"
-
-       When customizing the base_path, the  directory  must  exist,  otherwise
-       Gemstash will fail to run.  Thus, if you want to use /var/gemstash like
-       in the previous example, make sure to mkdir /var/gemstash and grant ac-
-       cess to the directory for the user you run Gemstash with.
-
-   1mDATABASE0m
-       The  :db_adapter	 configuration key specifies what database you will be
-       using.  The default :db_adapter is  sqlite3  (https://www.sqlite.org/),
-       which  will  use	 a  database file located within your :base_path.  The
-       database file will always be named gemstash.db.
-
-       You  may	 also	use   postgres	 (http://www.postgresql.org/),	 mysql
-       (http://www.mysql.com/),	     or	    mysql2     (http://sequel.jeremye-
-       vans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)   for
-       your :db_adapter.  When using any of these options, you need to specify
-       the :db_url to point to an existing database.  Here is an example  con-
-       figuration to use the postgres adapter:
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :db_adapter: postgres
-	      :db_url: postgres:///gemstash
-	      :db_connection_options: # Sequel.connect options
-		:connect_timeout: 10
-		:read_timeout: 5
-		:timeout: 30
-
-       Regardless  of  the adapter you choose, the database will automatically
-       migrate to your version of Gemstash whenever the	 database  is  needed.
-       You  only  need	to ensure the database exists and Gemstash will do the
-       rest, except for sqlite3 (for which Gemstash will also create the data-
-       base for you).
-
-   1mCACHE0m
-       Certain	things	(like dependencies) are cached in memory.  This avoids
-       web calls to the gem source, and database calls for private gems.
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :cache_type: memory
-	      :cache_max_size: 2000
-
-       This configuration uses the default memory cache, and has increased the
-       cache_max_size setting from its default of 500 items.
-
-       The  memory  cache  can	optionally  be	swapped	 out  with a Memcached
-       (http://memcached.org/) server (or cluster of servers).
-
-       To use Memcached, use the memcached :cache_type configuration.
-
-       Provide the servers as a comma-separated list to the :memcached_servers
-       configuration key:
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :cache_type: memcached
-	      :memcached_servers: memcached1.local:11211,memcached2.local:11211
-	      :cache_expiration: 1800
-
-       All  caching expires in cache_expiration number of seconds.  Default is
-       1800 seconds (30 minutes).  This option applies to all caching.
-
-   1mSERVER0m
-       Gemstash uses Puma (http://puma.io/) and Rack  (http://rack.github.io/)
-       as  the server.	Alternate server configurations are not currently sup-
-       ported,	but  you  can  take  a	look   at   the	  Puma	 configuration
-       (https://github.com/rubygems/gemstash/blob/master/lib/gemstash/puma.rb)
-       and  the	 rackup	 file  (https://github.com/rubygems/gemstash/blob/mas-
-       ter/lib/gemstash/config.ru) for inspiration.
-
-       While  the  server is not customizable, the way Gemstash binds the port
-       can be changed.	To change the binding, update the :bind	 configuration
-       key:
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :bind: tcp://0.0.0.0:4242
-
-       This	 maps	   directly	 to	the	Puma	 bind	  flag
-       (https://github.com/puma/puma#binding-tcp--sockets), and	 will  support
-       anything valid for that flag.
-
-       The   number  of	 threads  Puma	uses  is  also	customizable  via  the
-       :puma_threads configuration key.	 The default is 16.
-
-   1mPROTECTED FETCH0m
-       Gemstash by default allows unauthenticated  access  for	private	 gems.
-       Authenticated  access  is available via the :protected_fetch configura-
-       tion key.
-
-	      # ~/.gemstash/config.yml
-	      ---
-	      :protected_fetch: true
-
-       More details  on	 protected_fetch  are  here  (gemstash	help  private-
-       gems.7).
-
-   1mFETCH TIMEOUT0m
-       The  default  fetch timeout is 20 seconds.  Use the :fetch_timeout con-
-       figuration key to change it.
-
-	      ---
-	      :fetch_timeout: 20
-
-   1mCONFIG FILE LOCATION0m
-       By default, configuration for  Gemstash	will  be  at  ~/.gemstash/con-
-       fig.yml.	  This can be changed by providing the --config-file option to
-       the various Gemstash commands:
-
-	      $ gemstash setup --config-file ./gemstash-config.yml
-	      $ gemstash authorize --config-file ./gemstash-config.yml
-	      $ gemstash start --config-file ./gemstash-config.yml
-	      $ gemstash stop --config-file ./gemstash-config.yml
-	      $ gemstash status --config-file ./gemstash-config.yml
-
-       When providing --config-file to gemstash setup, the provided file  will
-       be  output to with the provided configuration.  1mThis will overwrite 22many
-       existing configuration.	If  the	 file  doesn't	exist  when  providing
-       --config-file  to  gemstash  start, gemstash stop, gemstash status, and
-       gemstash authorize, the default configuration will be used.
-
-   1mERB PARSED CONFIG0m
-       You may also create a  ~/.gemstash/config.yml.erb  file.	  If  present,
-       this will be used instead of ~/.gemstash/config.yml.  For example, with
-       this you can use environment variables in the config:
-
-	      # ~/.gemstash/config.yml.erb
-	      ---
-	      :db_adapter: postgres
-	      :db_url: <%= ENV["DATABASE_URL"] %>
-
-
-
-			       October 28, 2015		 gemstash-customize(7)

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

@@ -1,29 +1 @@
-gemstash-debugging(7)					 gemstash-debugging(7)
 
-
-
-1mDEBUGGING GEMSTASH0m
-       If  you	are  finding  Gemstash isn't behaving as you would expect, you
-       might want to start by looking at the server log.  You can find the log
-       at  server.log within your base directory.  By default, this will be at
-       ~/.gemstash/server.log.
-
-       You might find it easier to view the log directly in your terminal.  If
-       you  run	 Gemstash  in non-daemonized form (gemstash help start.1), the
-       log will be output directly to standard out:
-
-	      $ gemstash start --no-daemonize
-
-       You can also check the status (gemstash help status.1) of the server:
-
-	      $ gemstash status
-
-       The  server  status  is	checked	 by   passing	through	  to   pumactl
-       (https://github.com/puma/puma#pumactl).
-
-       If  you	find  a	 bug,  please  don't  hesitate	to  open  a bug report
-       (https://github.com/rubygems/gemstash#contributing)!
-
-
-
-			       October 28, 2015		 gemstash-debugging(7)

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

@@ -1,59 +1 @@
-gemstash-deploy(7)					    gemstash-deploy(7)
 
-
-
-1mDEPLOYING GEMSTASH0m
-       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 bundle
-       exec.  Alternatively, you can gem uninstall gemstash  and  gem  install
-       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
-
-   1mMONITORING0m
-       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.
-
-   1mDOWNGRADING0m
-       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.txt

@@ -1,33 +1 @@
-gemstash-mirror(7)					    gemstash-mirror(7)
 
-
-
-1mUSING GEMSTASH AS A MIRROR0m
-       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.
-
-1mSIMPLER GEMSTASH MIRRORS0m
-       1mThis feature requires Bundler to be at least version 1.11.0.0m
-
-       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.txt

@@ -1,71 +1 @@
-gemstash-multiple-sources(7)			  gemstash-multiple-sources(7)
 
-
-
-1mMULTIPLE GEM SOURCES0m
-       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.
-
-   1mDEFAULT SOURCE0m
-       When you don't provide an explicit source (as with the Quickstart Guide
-       (../readme.md#quickstart-guide)),  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.
-
-   1mBUNDLING WITH MULTIPLE SOURCES0m
-       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.
-
-   1mREDIRECTING0m
-       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,156 +1 @@
-gemstash-private-gems(7)			      gemstash-private-gems(7)
 
-
-
-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
-       (../readme.md#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 gemstash authorize command to create the
-       API key:
-
-	      $ gemstash authorize
-	      Your new key is: e374e237fdf5fa5718d2a21bd63dc911
-
-       This new key can push, yank, 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.
-
-   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   private-example/pkg/private-exam-
-       ple-0.1.0.gem.
-
-   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 /private portion of the --host option tells Gemstash you are inter-
-       acting with the private gems.  Gemstash will not let you push, or  yank
-       from anything except /private.
-
-   1mBUNDLING0m
-       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
-
-   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 /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 (yet),  so  you	need  to  specify  the	host  via  the
-       RUBYGEMS_HOST environment 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 $ gemstash
-       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)