gemstash 2.2.0 → 2.2.1

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

@@ -0,0 +1,316 @@
+<!-- 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-customize" "7" "October 28, 2015" "" ""
+.hy
+.SH Customizing the Server
+.PP
+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
+Gemstash uses, and how Gemstash caches certain requests.
+.SS Setup
+.PP
+Several customizable options are available via an interactive Gemstash
+command.
+Run \f[V]gemstash setup\f[R] and answer the questions it provides (a
+blank answer will use the default value):
+.RS
+.PP
+$ gemstash setup
+.PD 0
+.P
+.PD
+Where should files go?
+[\[ti]/.gemstash]
+.PD 0
+.P
+.PD
+Cache with what?
+[MEMORY, memcached] \f[B]memcached\f[R]
+.PD 0
+.P
+.PD
+What is the comma separated Memcached servers?
+[localhost:11211]
+.PD 0
+.P
+.PD
+What database adapter?
+[SQLITE3, postgres, mysql, mysql2] \f[B]postgres\f[R]
+.PD 0
+.P
+.PD
+Where is the database?
+[postgres:///gemstash]
+.PD 0
+.P
+.PD
+Checking that the cache is available
+.PD 0
+.P
+.PD
+Checking that the database is available
+.PD 0
+.P
+.PD
+The database is not available
+.PD 0
+.P
+.PD
+.RE
+.PP
+Once you\[cq]ve answered the questions, some checks will be made to
+ensure the configuration will work.
+For example, the database didn\[cq]t exist in the previous example, so
+the command failed and the configuration wasn\[cq]t saved.
+If the command passes, you may provide the \f[V]--redo\f[R] option to
+force configuration to be redone:
+.RS
+.PP
+\f[V]$ gemstash setup --redo\f[R]
+.PD 0
+.P
+.PD
+Where should files go?
+[\[ti]/.gemstash]
+.PD 0
+.P
+.PD
+Cache with what?
+[MEMORY, memcached] \f[B]memcached\f[R]
+.PD 0
+.P
+.PD
+What is the comma separated Memcached servers?
+[localhost:11211]
+.PD 0
+.P
+.PD
+What database adapter?
+[SQLITE3, postgres, mysql, mysql2]
+.PD 0
+.P
+.PD
+Checking that the cache is available
+.PD 0
+.P
+.PD
+Checking that the database is available
+.PD 0
+.P
+.PD
+You are all setup!
+.PD 0
+.P
+.PD
+.RE
+.PP
+Once all checks have passed, Gemstash will store your answers in the
+configuration file located at \f[V]\[ti]/.gemstash/config.yml\f[R].
+.SS Files
+.PP
+Storage in Gemstash defaults to \f[V]\[ti]/.gemstash\f[R] unless
+otherwise specified.
+You can change this in your config file via the \f[V]:base_path\f[R]
+key:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:base_path: \[dq]/var/gemstash\[dq]
+\f[R]
+.fi
+.PP
+When customizing the \f[V]base_path\f[R], the directory must exist,
+otherwise Gemstash will fail to run.
+Thus, if you want to use \f[V]/var/gemstash\f[R] like in the previous
+example, make sure to \f[V]mkdir /var/gemstash\f[R] and grant access to
+the directory for the user you run Gemstash with.
+.SS Database
+.PP
+The \f[V]:db_adapter\f[R] configuration key specifies what database you
+will be using.
+The default \f[V]:db_adapter\f[R] is
+\f[V]sqlite3\f[R] (https://www.sqlite.org/), which will use a database
+file located within your \f[V]:base_path\f[R].
+The database file will always be named \f[V]gemstash.db\f[R].
+.PP
+You may also use \f[V]postgres\f[R] (http://www.postgresql.org/),
+\f[V]mysql\f[R] (http://www.mysql.com/), or
+\f[V]mysql2\f[R] (http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)
+for your \f[V]:db_adapter\f[R].
+When using any of these options, you need to specify the
+\f[V]:db_url\f[R] to point to an existing database.
+Here is an example configuration to use the \f[V]postgres\f[R] adapter:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:db_adapter: postgres
+:db_url: postgres:///gemstash
+:db_connection_options: # Sequel.connect options
+  :connect_timeout: 10
+  :read_timeout: 5
+  :timeout: 30
+\f[R]
+.fi
+.PP
+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 \f[V]sqlite3\f[R] (for which Gemstash will also create
+the database for you).
+.SS Cache
+.PP
+Certain things (like dependencies) are cached in memory.
+This avoids web calls to the gem source, and database calls for private
+gems.
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:cache_type: memory
+:cache_max_size: 2000
+\f[R]
+.fi
+.PP
+This configuration uses the default \f[V]memory\f[R] cache, and has
+increased the \f[V]cache_max_size\f[R] setting from its default of 500
+items.
+.PP
+The memory cache can optionally be swapped out with a
+Memcached (http://memcached.org/) server (or cluster of servers).
+.PP
+To use Memcached, use the \f[V]memcached\f[R] \f[V]:cache_type\f[R]
+configuration.
+.PP
+Provide the servers as a comma-separated list to the
+\f[V]:memcached_servers\f[R] configuration key:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:cache_type: memcached
+:memcached_servers: memcached1.local:11211,memcached2.local:11211
+:cache_expiration: 1800
+\f[R]
+.fi
+.PP
+All caching expires in \f[V]cache_expiration\f[R] number of seconds.
+Default is 1800 seconds (30 minutes).
+This option applies to all caching.
+.SS Server
+.PP
+Gemstash uses Puma (http://puma.io/) and Rack (http://rack.github.io/)
+as the server.
+Alternate server configurations are not currently supported, 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/master/lib/gemstash/config.ru)
+for inspiration.
+.PP
+While the server is not customizable, the way Gemstash binds the port
+can be changed.
+To change the binding, update the \f[V]:bind\f[R] configuration key:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:bind: tcp://0.0.0.0:4242
+\f[R]
+.fi
+.PP
+This maps directly to the Puma bind
+flag (https://github.com/puma/puma#binding-tcp--sockets), and will
+support anything valid for that flag.
+.PP
+The number of threads Puma uses is also customizable via the
+\f[V]:puma_threads\f[R] configuration key.
+The default is \f[V]16\f[R].
+.SS Protected Fetch
+.PP
+Gemstash by default allows unauthenticated access for private gems.
+Authenticated access is available via the \f[V]:protected_fetch\f[R]
+configuration key.
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml
+---
+:protected_fetch: true
+\f[R]
+.fi
+.PP
+More details on protected_fetch are here.
+.SS Fetch Timeout
+.PP
+The default fetch timeout is 20 seconds.
+Use the \f[V]:fetch_timeout\f[R] configuration key to change it.
+.IP
+.nf
+\f[C]
+---
+:fetch_timeout: 20
+\f[R]
+.fi
+.SS Config File Location
+.PP
+By default, configuration for Gemstash will be at
+\f[V]\[ti]/.gemstash/config.yml\f[R].
+This can be changed by providing the \f[V]--config-file\f[R] option to
+the various Gemstash commands:
+.IP
+.nf
+\f[C]
+$ 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
+\f[R]
+.fi
+.PP
+When providing \f[V]--config-file\f[R] to \f[V]gemstash setup\f[R], the
+provided file will be output to with the provided configuration.
+\f[B]This will overwrite\f[R] any existing configuration.
+If the file doesn\[cq]t exist when providing \f[V]--config-file\f[R] to
+\f[V]gemstash start\f[R], \f[V]gemstash stop\f[R],
+\f[V]gemstash status\f[R], and \f[V]gemstash authorize\f[R], the default
+configuration will be used.
+.SS ERB parsed config
+.PP
+You may also create a \f[V]\[ti]/.gemstash/config.yml.erb\f[R] file.
+If present, this will be used instead of
+\f[V]\[ti]/.gemstash/config.yml\f[R].
+For example, with this you can use environment variables in the config:
+.IP
+.nf
+\f[C]
+# \[ti]/.gemstash/config.yml.erb
+---
+:db_adapter: postgres
+:db_url: <%= ENV[\[dq]DATABASE_URL\[dq]] %>
+\f[R]
+.fi

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

@@ -1 +1,188 @@
+gemstash-customize(7)					 gemstash-customize(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+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 1mgemstash setup 22mand 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 1m--redo 22moption
+       to force configuration to be redone:
+
+	      1m$ gemstash setup --redo0m
+	      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 1m~/.gemstash/config.yml22m.
+
+   1mFiles0m
+       Storage in Gemstash defaults to 1m~/.gemstash 22munless otherwise specified.
+       You can change this in your config file via the 1m:base_path 22mkey:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :base_path: "/var/gemstash"
+
+       When customizing the 1mbase_path22m, the  directory  must  exist,  otherwise
+       Gemstash will fail to run.  Thus, if you want to use 1m/var/gemstash 22mlike
+       in the previous example, make sure to 1mmkdir /var/gemstash 22mand grant ac-
+       cess to the directory for the user you run Gemstash with.
+
+   1mDatabase0m
+       The  1m:db_adapter  22mconfiguration key specifies what database you will be
+       using.  The default 1m:db_adapter 22mis	1msqlite3  22m(https://www.sqlite.org/),
+       which  will  use  a  database file located within your 1m:base_path22m.	The
+       database file will always be named 1mgemstash.db22m.
+
+       You  may  also	use   1mpostgres   22m(http://www.postgresql.org/),   1mmysql0m
+       (http://www.mysql.com/),      or     1mmysql2	 22m(http://sequel.jeremye-
+       vans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)   for
+       your 1m:db_adapter22m.  When using any of these options, you need to specify
+       the 1m:db_url 22mto point to an existing database.  Here is an example  con-
+       figuration to use the 1mpostgres 22madapter:
+
+	      # ~/.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 1msqlite3 22m(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 1mmemory 22mcache, and has increased the
+       1mcache_max_size 22msetting 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 1mmemcached :cache_type 22mconfiguration.
+
+       Provide the servers as a comma-separated list to the 1m:memcached_servers0m
+       configuration key:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :cache_type: memcached
+	      :memcached_servers: memcached1.local:11211,memcached2.local:11211
+	      :cache_expiration: 1800
+
+       All  caching expires in 1mcache_expiration 22mnumber 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 1m:bind  22mconfiguration
+       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
+       1m:puma_threads 22mconfiguration key.  The default is 1m1622m.
+
+   1mProtected Fetch0m
+       Gemstash by default allows unauthenticated  access  for	private  gems.
+       Authenticated  access  is available via the 1m:protected_fetch 22mconfigura-
+       tion key.
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :protected_fetch: true
+
+       More details on protected_fetch are here.
+
+   1mFetch Timeout0m
+       The default fetch timeout is 20 seconds.  Use the  1m:fetch_timeout  22mcon-
+       figuration key to change it.
+
+	      ---
+	      :fetch_timeout: 20
+
+   1mConfig File Location0m
+       By  default,  configuration  for  Gemstash  will be at 1m~/.gemstash/con-0m
+       1mfig.yml22m.  This can be changed by providing the 1m--config-file 22moption  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 1m--config-file 22mto 1mgemstash setup22m, 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
+       1m--config-file 22mto 1mgemstash start22m, 1mgemstash stop22m,  1mgemstash  status22m,  and
+       1mgemstash authorize22m, the default configuration will be used.
+
+   1mERB parsed config0m
+       You  may  also  create  a 1m~/.gemstash/config.yml.erb 22mfile.	If present,
+       this will be used instead of 1m~/.gemstash/config.yml22m.  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

@@ -0,0 +1,49 @@
+<!-- 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-debugging" "7" "October 28, 2015" "" ""
+.hy
+.SH Debugging Gemstash
+.PP
+If you are finding Gemstash isn\[cq]t behaving as you would expect, you
+might want to start by looking at the server log.
+You can find the log at \f[V]server.log\f[R] within your base directory.
+By default, this will be at \f[V]\[ti]/.gemstash/server.log\f[R].
+.PP
+You might find it easier to view the log directly in your terminal.
+If you run Gemstash in non-daemonized form, the log will be output
+directly to standard out:
+.IP
+.nf
+\f[C]
+$ gemstash start --no-daemonize
+\f[R]
+.fi
+.PP
+You can also check the status of the server:
+.IP
+.nf
+\f[C]
+$ gemstash status
+\f[R]
+.fi
+.PP
+The server status is checked by passing through to
+pumactl (https://github.com/puma/puma#pumactl).
+.PP
+If you find a bug, please don\[cq]t hesitate to open a bug
+report (https://github.com/rubygems/gemstash#contributing)!

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

@@ -1 +1,31 @@
+gemstash-debugging(7)					 gemstash-debugging(7)
 
+
+
+<!-- Automatically generated by Pandoc -->
+
+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  1mserver.log 22mwithin your base directory.	By default, this will be at
+       1m~/.gemstash/server.log22m.
+
+       You might find it easier to view the log directly in your terminal.  If
+       you run Gemstash in non-daemonized form, the log will be output direct-
+       ly to standard out:
+
+	      $ gemstash start --no-daemonize
+
+       You can also check the status 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

@@ -0,0 +1,87 @@
+<!-- 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-deploy" "7" "October 25, 2015" "" ""
+.hy
+.SH Deploying Gemstash
+.PP
+Bundler is here for the rescue to keep Gemstash up to date!
+Create a \f[V]Gemfile\f[R] pointing to Gemstash:
+.IP
+.nf
+\f[C]
+# ./Gemfile
+source \[dq]https://rubygems.org\[dq]
+gem \[dq]gemstash\[dq]
+\f[R]
+.fi
+.PP
+Then \f[V]bundle\f[R] to create your \f[V]Gemfile.lock\f[R].
+When you are ready to upgrade, simply \f[V]bundle update\f[R].
+You may need to run \f[V]gemstash\f[R] via \f[V]bundle exec\f[R].
+Alternatively, you can \f[V]gem uninstall gemstash\f[R] and
+\f[V]gem install gemstash\f[R] when you want to upgrade.
+.PP
+Gemstash will automatically run any necessary migrations, so updating
+the gem is all that needs to be done.
+.PP
+It is probably wise to stop Gemstash before upgrading, then starting
+again once you are done:
+.IP
+.nf
+\f[C]
+$ bundle exec gemstash stop
+$ bundle update
+$ bundle exec gemstash start
+\f[R]
+.fi
+.SS Monitoring
+.PP
+Health monitoring is built in to Gemstash using the
+server_health_check-rack (https://github.com/on-site/server_health_check-rack)
+gem.
+If you request \f[V]/health\f[R] from your Gemstash instance, you will
+get a JSON response along with an HTTP status code indicating success or
+failure.
+The JSON response will look something like this for a success case:
+.IP
+.nf
+\f[C]
+{
+  \[dq]status\[dq]: {
+    \[dq]heartbeat\[dq]: \[dq]OK\[dq],
+    \[dq]storage_read\[dq]: \[dq]OK\[dq],
+    \[dq]storage_write\[dq]: \[dq]OK\[dq],
+    \[dq]db_read\[dq]: \[dq]OK\[dq],
+    \[dq]db_write\[dq]: \[dq]OK\[dq]
+  }
+}
+\f[R]
+.fi
+.PP
+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\[cq]t interact
+with storage or the database, you can use \f[V]/health/heartbeat\f[R]
+which will always respond with a success while your Gemstash server is
+running.
+.SS Downgrading
+.PP
+It is not recommended to go backwards in Gemstash versions.
+Migrations may have run that could leave the database in a bad state.