gemstash 2.0.0 → 2.1.0

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

@@ -1,66 +1,187 @@
+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

@@ -0,0 +1,34 @@
+.\" Automatically generated by Pandoc 2.5
+.\"
+.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[C]server.log\f[R] within your base directory.
+By default, this will be at \f[C]\[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 (gemstash help start.1), 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 (gemstash help status.1) 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,66 +1,29 @@
+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

@@ -0,0 +1,72 @@
+.\" Automatically generated by Pandoc 2.5
+.\"
+.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[C]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[C]bundle\f[R] to create your \f[C]Gemfile.lock\f[R].
+When you are ready to upgrade, simply \f[C]bundle update\f[R].
+You may need to run \f[C]gemstash\f[R] via \f[C]bundle exec\f[R].
+Alternatively, you can \f[C]gem uninstall gemstash\f[R] and
+\f[C]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[C]/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[C]/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.

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

@@ -1,66 +1,59 @@
+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)